Business API

Integration Guide

Pull your team's processed receipts into your own accounting, ERP, or reporting system. This API is read-only and scoped to a single business — every request returns only that business's data.

Overview

The Business API lets you fetch processed receipts — the same data available in your Output and master CSV export — as JSON, or pull the export file directly, authenticated by a long-lived API key instead of logging in.

Generate a key from Business Dashboard → API Access (owner/admin only).

Authentication

Every request must include your API key in one of two headers. Use whichever your integration platform makes easier — they're equivalent.

# Preferred Authorization: Bearer rai_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # Also accepted — useful if your platform can't set a custom Authorization header X-Api-Key: rai_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys are shown once at creation time and stored by us only as a hash — if you lose one, revoke it and generate a new one. A key is tied to one business and inherits no individual user's permissions beyond read access to that business's processed receipts.

Base URL & Versioning

https://tafity.com/api/v1/

All endpoints are versioned under /api/v1/. Breaking changes (removed fields, changed semantics) will ship under a new /api/v2/ path rather than altering v1 in place — additive changes (new optional fields, new endpoints) may land in v1 without notice.

Rate Limits

600 requests per hour, per API key. Exceeding it returns 429 Too Many Requests. If you need a higher limit for a legitimate sync workload, contact us.

Errors

All errors return a JSON body of the form {"success": false, "error": "..."} with a matching HTTP status code.

Status	Meaning
`401`	Missing, invalid, or revoked API key.
`404`	Receipt not found (wrong UUID, or it belongs to a different business).
`405`	Wrong HTTP method — every endpoint in this API is `GET` only.
`429`	Rate limit exceeded — see above.
`400`	Invalid query parameter (e.g. malformed `updated_since`).

List Receipts

GET/api/v1/receipts

Returns processed (status=done) receipts across every member of your team, newest first. Supports filtering and pagination.

Query parameters

Param	Type	Description
`from`	date	Only receipts dated on/after this date. `YYYY-MM-DD`.
`to`	date	Only receipts dated on/before this date. `YYYY-MM-DD`.
`updated_since`	datetime	ISO 8601. For incremental sync — only receipts modified at/after this time. Covers edits made via the Preview/Edit UI too.
`q`	string	Free-text search across merchant name, description, and receipt number.
`page`	integer	Default `1`.
`per_page`	integer	Default `50`, maximum `100`.

Example request

curl "https://tafity.com/api/v1/receipts?from=2026-07-01&per_page=2" \ -H "Authorization: Bearer rai_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Example response

{ "success": true, "business": { "id": 2, "name": "Acme Co" }, "pagination": { "page": 1, "per_page": 2, "total": 14, "total_pages": 7 }, "receipts": [ { "uuid": "33333333-4444-5555-6666-777777777777", "receipt_number": "B-002", "business_name": "Total Energies", "description": "Fuel", "category": null, "amount": 5000, "tax": 0, "currency": "KES", "payment_method": "card", "etims_code": null, "ref_number": null, "receipt_date": "2026-07-21", "receipt_time": "11:00:00", "status": "done", "added_by": { "name": "Jane Wanjiru", "designation": "Accountant" }, "created_at": "2026-07-21 09:12:03", "processed_at": "2026-07-21 09:12:07", "updated_at": "2026-07-21 09:12:07" } ] }

Get a Receipt

GET/api/v1/receipts?uuid={uuid}

Fetch a single receipt by its UUID. Returns the same object shape as the list endpoint, under a receipt key instead of receipts.

curl "https://tafity.com/api/v1/receipts?uuid=33333333-4444-5555-6666-777777777777" \ -H "Authorization: Bearer rai_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Export (CSV / Excel)

GET/api/v1/export

Streams the same "master" export file available from the business dashboard — every team member's receipts, with Added By and Designation columns. Useful for systems that ingest a file on a schedule rather than parse JSON.

Param	Type	Description
`format`	string	`csv` (default), `xlsx`, or `pdf`.
`from` / `to`	date	Same as the list endpoint.
`q`	string	Same as the list endpoint.

curl "https://tafity.com/api/v1/export?format=csv" \ -H "Authorization: Bearer rai_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ -o receipts.csv

Receipt Object

Field	Type	Description
`uuid`	string	Stable identifier for this receipt — use this, not the row order, to de-duplicate across syncs.
`receipt_number`	string\|null	Receipt/invoice number as printed on the receipt, if detected.
`business_name`	string\|null	The merchant/vendor name on the receipt (e.g. "Java House") — not your ReceiptAI business account name.
`amount` / `tax`	number\|null	Total and tax (VAT) amount, in `currency`.
`currency`	string	3-letter currency code, e.g. `KES`.
`added_by.name`	string\|null	Full name of the team member who uploaded this receipt.
`added_by.designation`	string\|null	That team member's job title, as set on their account. `null` if not filled in.
`updated_at`	datetime	Bumped whenever the receipt is edited — the field to watch for incremental sync via `updated_since`.

Pagination

The list endpoint returns a pagination object alongside receipts. Increment page until page >= total_pages. For ongoing sync, prefer polling with updated_since set to the last time you synced, rather than re-paginating the entire history each run.

Code Examples

Node.js

const res = await fetch('https://tafity.com/api/v1/receipts?updated_since=2026-08-01T00:00:00Z', { headers: { 'Authorization': 'Bearer ' + process.env.RECEIPTAI_KEY } }); const data = await res.json(); for (const r of data.receipts) { // upsert into your own system, keyed on r.uuid }

Python

import requests resp = requests.get( "https://tafity.com/api/v1/receipts", headers={"Authorization": f"Bearer {RECEIPTAI_KEY}"}, params={"updated_since": last_sync_iso}, ) for r in resp.json()["receipts"]: upsert(r) # keyed on r["uuid"]

PHP

<?php $ch = curl_init('https://tafity.com/api/v1/receipts?updated_since=2026-08-01T00:00:00Z'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('RECEIPTAI_KEY')], ]); $response = curl_exec($ch); curl_close($ch); $data = json_decode($response, true); foreach ($data['receipts'] as $r) { // upsert into your own system, keyed on $r['uuid'] }

Java

import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import org.json.JSONArray; import org.json.JSONObject; // Maven/Gradle dependency: org.json:json public void syncReceipts() throws Exception { HttpClient client = HttpClient.newHttpClient(); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://tafity.com/api/v1/receipts?updated_since=2026-08-01T00:00:00Z")) .header("Authorization", "Bearer " + System.getenv("RECEIPTAI_KEY")) .GET() .build(); HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString()); JSONObject data = new JSONObject(response.body()); JSONArray receipts = data.getJSONArray("receipts"); for (int i = 0; i < receipts.length(); i++) { JSONObject r = receipts.getJSONObject(i); upsert(r); // keyed on r.getString("uuid") } }

Questions or need a rate-limit increase? support@tafity.com