Authentication

Authenticate your account when using the API by including your secret API key in the request. You can manage your API keys in the Outlay Dashboard. Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password.

Note: All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Pagination

All top-level API resources have support for bulk fetches via "list" API methods. For instance, you can list receipts, workspaces, and users. These list API methods share a common structure, taking at least these two parameters: limit, and starting_after.

Outlay utilizes cursor-based pagination. You must pass the ID of the last object received to fetch the next page.

Errors

Outlay uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted). Codes in the 5xx range indicate an error with Outlay's servers.

Create a Receipt

Creates a new receipt object. This endpoint triggers the asynchronous AI extraction engine. You will receive an immediate response with a receipt ID, but the extraction results (merchant name, amount, GST) will be populated asynchronously. Use webhooks to be notified when extraction completes.

Parameters

Name Type Description
file
Required 		binary The receipt image or PDF file to be processed. Max size 10MB.
workspace_id
Optional 		string The ID of the workspace. If not provided, defaults to your primary workspace.

List Workspaces

Returns a list of your workspaces. The workspaces are returned sorted by creation date, with the most recently created workspaces appearing first.

List Users

Returns a list of users attached to a specific workspace. You must provide the workspace ID to list its members.

Events Overview

Outlay can send webhook events that notify your application any time an event happens on your account. This is particularly useful for asynchronous operations like AI receipt extraction, which can take a few seconds to complete.

Signature Verification

Outlay can optionally sign the webhook events it sends to your endpoints by including a signature in each event's Outlay-Signature header. This allows you to verify that the events were sent by Outlay, not by a third party.

cURL · Authentication 
curl https://api.outlay.site/v2/workspaces \
  -u sk_live_abc123...:
cURL · Create Receipt 
curl https://api.outlay.site/v2/receipts \
  -u sk_live_abc123...: \
  -F file=@/path/to/uber_receipt.pdf \
  -F workspace_id=ws_9x8y7z
JSON · Response 
{
  "id": "re_12345abc",
  "object": "receipt",
  "status": "processing",
  "created_at": 1694683059,
  "extracted_data": null
}