Expenses API (0.1)

Download OpenAPI specification:Download

The Expenses API allows you to manage accounting and expenses information.

Card Expenses

View and manage card expenses data.

List expenses

List expenses under the same account. Admin and bookkeeper have access to any expense, and regular users can only access their own.

SecurityOAuth2
Request
query Parameters
expand[]
Array of strings or null

Get additional details for the expense, e.g. merchant mcc code, by passing in expand[]=merchant. Query parameters include location, department, merchant, receipts.download_uris, user, budget and payment.

Example: expand[]= ?expand[]=merchant&expand[]=location
user_id[]
Array of strings or null

Get expenses belong to provided user(s).

parent_expense_id[]
Array of strings or null

Get itemized expenses belong to provided parent expenses ID(s).

budget_id[]
Array of strings or null
status[]
Array of strings or null (ExpenseStatus)
Enum: "DRAFT" "SUBMITTED" "APPROVED" "OUT_OF_POLICY" "VOID" "CANCELED" "SPLIT" "SETTLED"
payment_status[]
Array of strings or null (ExpensePaymentStatus)
Enum: "NOT_STARTED" "PROCESSING" "CANCELED" "DECLINED" "CLEARED" "REFUNDING" "REFUNDED" "CASH_ADVANCE" "CREDITED" "AWAITING_PAYMENT" "SCHEDULED"
purchased_at_start
string or null <date-time>

Shows only expenses with a purchased_at on or after this date-time. This parameter is the date-time notation as defined by RFC 3339, section 5.6, e.g. 2022-11-12T23:59:59.999

Example: purchased_at_start= 2023-01-01T23:59:59.999
purchased_at_end
string or null <date-time>

Shows only expenses with a purchased_at on or before this date-time. This parameter is the date-time notation as defined by RFC 3339, section 5.6, e.g. 2022-11-12T23:59:59.999

Example: purchased_at_end= 2023-01-10T23:59:59.999
load_custom_fields
boolean or null

Load custom fields for the expenses.

cursor
string or null

The cursor to use for pagination. This is the next_cursor value returned from the previous response.

limit
integer or null <int32>

Controls the maximum number of expenses returned in the response, cant be greater than 1000.

Responses
200

List expenses response.

400

Bad request

401

Unauthorized

403

Forbidden

get/v1/expenses/card
Request samples
Response samples
application/json
{
  • "next_cursor": "string",
  • "items": [
    ]
}

Get an expense

Get an expense by its ID.

SecurityOAuth2
Request
path Parameters
expense_id
required
string
query Parameters
expand[]
Array of strings or null

Get additional details for the expense, e.g. merchant mcc code, by passing in expand[]=merchant. Query parameters include location, department, merchant, receipts.download_uris, user, budget and payment.

Example: expand[]= ?expand[]=merchant&expand[]=location
load_custom_fields
boolean or null

Load custom fields for the expense.

Responses
200

Get an expense response.

400

Bad request

401

Unauthorized

403

Forbidden

404

Not Found

get/v1/expenses/card/{expense_id}
Request samples
Response samples
application/json
{
  • "id": "string",
  • "memo": "string",
  • "location_id": "string",
  • "location": {
    },
  • "address": {
    },
  • "department_id": "string",
  • "department": {
    },
  • "updated_at": "2019-08-24T14:15:22Z",
  • "payment_posted_at": "2019-08-24T14:15:22Z",
  • "category": "ADVERTISING_AND_MARKETING",
  • "merchant_id": "string",
  • "merchant": {
    },
  • "receipts": [
    ],
  • "budget_id": "string",
  • "budget": {
    },
  • "expense_type": "CARD",
  • "original_amount": {
    },
  • "billing_amount": {
    },
  • "budget_amount": {
    },
  • "purchased_at": "2019-08-24T14:15:22Z",
  • "status": "DRAFT",
  • "payment_status": "NOT_STARTED",
  • "user_id": "string",
  • "user": {
    },
  • "payment": {
    },
  • "custom_fields": [
    ],
  • "trip_id": "string"
}

Update an expense

Update an expense. Admin and bookkeeper have access to any expense, and regular users can only access their own.

SecurityOAuth2
Request
path Parameters
expense_id
required
string
Request Body schema: application/json
memo
string or null

Expense memo.

Responses
200

Update an expense response.

400

Bad request

401

Unauthorized

403

Forbidden

404

Not Found

put/v1/expenses/card/{expense_id}
Request samples
application/json
{
  • "memo": "string"
}
Response samples
application/json
{
  • "id": "string",
  • "memo": "string",
  • "location_id": "string",
  • "department_id": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "category": "ADVERTISING_AND_MARKETING",
  • "merchant_id": "string",
  • "budget_id": "string",
  • "original_amount": {
    },
  • "billing_amount": {
    },
  • "purchased_at": "2019-08-24T14:15:22Z",
  • "status": "DRAFT",
  • "payment_status": "NOT_STARTED"
}

Receipt Match

Upload receipt and match automatically.

Create a new receipt match

The uri will be a pre-signed S3 URL allowing you to upload the receipt securely. This URL can only be used for a PUT operation and expires 30 minutes after its creation. Once your upload is complete, we will try to match the receipt with existing expenses.

Refer to these docs on how to upload to this pre-signed S3 URL. We highly recommend using one of AWS SDKs if they're available for your language to upload these files.

SecurityOAuth2
Request
Request Body schema: application/json
receipt_name
required
string

The name of the receipt (with the file extension). It will be used in the matching result email.

Responses
201

Create a new receipt match response.

400

Bad request

401

Unauthorized

post/v1/expenses/card/receipt_match
Request samples
application/json
{
  • "receipt_name": "string"
}
Response samples
application/json
{
  • "id": "string",
  • "uri": "string"
}

Receipt Upload

Create a new receipt upload

The uri will be a pre-signed S3 URL allowing you to upload the receipt securely. This URL can only be used for a PUT operation and expires 30 minutes after its creation. Once your upload is complete, we will try to match the receipt with existing expenses.

Refer to these docs on how to upload to this pre-signed S3 URL. We highly recommend using one of AWS SDKs if they're available for your language to upload these files.

SecurityOAuth2
Request
path Parameters
expense_id
required
string
Request Body schema: application/json
receipt_name
required
string

The name of the receipt (with the file extension).

Responses
201

Upload a new receipt response.

400

Bad request

401

Unauthorized

403

Forbidden

404

Not Found

post/v1/expenses/card/{expense_id}/receipt_upload
Request samples
application/json
{
  • "receipt_name": "string"
}
Response samples
application/json
{
  • "id": "string",
  • "uri": "string"
}
Copyright © Brex 2019–2022. All rights reserved.