Files API

Every receipt Versa attaches to one of your transactions is a file. The receipt_retrieval.completed webhook lists those files, each with a signed download URL that expires after 15 minutes. The Files API lets you come back to them later (except receipts collected from your corporate card provider): fetch a fresh download URL for a file, or the receipt data Versa extracted from it, in the Versa receipt schema.

The Files API is served at https://api.versa.org/files and uses the same client credentials as the Events API and the Flags API.

Quick Example: Fetch a fresh download URL

curl https://api.versa.org/files/file_01kxb5d7qve00a78ns2gqj6xqs \
  -H 'Authorization: Basic CLIENT_ID:CLIENT_SECRET'

The file_id is the one a receipt_retrieval.completed event carried in receipts[]. Download the file from the returned url within 15 minutes, or ask again.

Authentication

Every request carries your client credentials in an Authorization header using the Basic scheme, either as the raw pair or base64-encoded:

Authorization: Basic CLIENT_ID:CLIENT_SECRET

Use a production client credential of your organization. A test credential is refused on both routes with 403 and the body {"error": "Test credentials are not accepted on the Files API"}. A missing or incorrect credential answers 401 with the body {"error": "Invalid client credentials"}. If Versa cannot complete the credential check, the request answers 503 with the body {"error": "Credential check unavailable"}; this applies to both routes of this API.

Every error on this API is a JSON object with a single error message. A file that is not yours, or that does not exist, answers 404 with {"error": "Not found"}; the two cases are deliberately indistinguishable.

API Reference

Get a file

GET https://api.versa.org/files/{file_id}

Returns the file with a freshly signed download URL. The response is the same object the webhook carries in receipts[].

Example Request

curl https://api.versa.org/files/file_01kxb5d7qve00a78ns2gqj6xqs \
  -H 'Authorization: Basic CLIENT_ID:CLIENT_SECRET'

Response

{
  "file_id": "file_01kxb5d7qve00a78ns2gqj6xqs",
  "url": "https://storage.googleapis.com/...",
  "size": 55555,
  "filetype": "application/pdf",
  "created": 1789776000
}

File fields

Get a file's extracted data

GET https://api.versa.org/files/{file_id}/extracted_data?schema_version=2.3.0

Returns the receipt Versa extracted from the file, as a Versa receipt in the schema version you ask for.

Query Parameters

Example Request

curl 'https://api.versa.org/files/file_01kxb5d7qve00a78ns2gqj6xqs/extracted_data?schema_version=2.3.0' \
  -H 'Authorization: Basic CLIENT_ID:CLIENT_SECRET'

Response

{
  "file_id": "file_01kxb5d7qve00a78ns2gqj6xqs",
  "extracted": 1789776120,
  "extraction_task_id": "agt_01kxb5dhwff00a78ns2gqj6xqs",
  "data": {
    "schema_version": "2.3.0",
    "header": {
      "currency": "usd",
      "total": 39488,
      "subtotal": 34000,
      "paid": 39488,
      "invoice_number": "H2513284",
      "invoiced_at": 1789776000
    },
    "itemization": {
      "lodging": {
        "check_in": 1789776000,
        "check_out": 1789948800,
        "location": {
          "name": "Courtland Grand Hotel"
        },
        "items": [
          {
            "description": "Room 1204",
            "amount": 34000,
            "quantity": 2.0,
            "unit_cost": 17000,
            "date": "2026-09-19"
          }
        ]
      }
    },
    "payments": [],
    "footer": {}
  }
}

The example is abridged: it shows one line item and leaves out the optional fields a receipt may carry.

Response fields

The extracted data is Versa's reading of the document and may be incomplete for an unusual layout. The file itself remains the record; the Flags API is the way to tell Versa a receipt is wrong.