Solutions ▼ Features ▼ Pricing API Log in Sign up Request a Demo
Log in Request Demo

API Docs

Getting Started
API Basics
Spending
Organization
Accounting
Webhooks

Getting Started with the API

Emburse’s API enables for the creation of expense cards at scale for custom business solutions as well as for third-party app integrations. Cards can be created with set spending limits and assigned with just an email. Some use cases include vendor payments, employee expense control, and fleet card management.

Check out our API documentation below, and sign up for an account when you are ready. Please reach out to support@emburse.com with any questions.

Register Your App

Before using Emburse's API, you must first be granted developer permissions which can be requested via contacting support@emburse.com.

After being granted developer permissions, go to the apps list and click "Create App". Once an app is created, you'll be given a client_id and client_secret which may be used to generate access tokens for API authentication.

Authentication

Emburse uses the OAuth2 protocol for managing access control and authorizations. In order to access Emburse's API endpoints, each request must include an access_token with its Authorization header: 

Authorization: Token ACCESS_TOKEN

For example, using curl, you can set the Authorization header as follows: 

curl -H "Authorization: Token zTF0vvvwWiYM06QDg9ZyTUac0HE1LC" https://api.emburse.com/v1/

Each access token grants your app access to data for a specific company and with specific privileges.

Access Tokens

After registering an app, you'll want to create an access_token. The easiest way to do so is via your app's settings page. From this page, you'll be able to generate a token which grants access to your company's Emburse account. You'll also be able to add a scope which limits the privileges being granted.

Once generated, an access_token does not expire but may be revoked by a company administrator. An access token may also be revoked via the API.

Idempotency Keys

The API supports the use of idempotency keys. An idempotency key may be used to safely retry requests without performing the same operation twice.

Idempotent requests are performed by specifying an Idempotency-Key: <key> header.

When an idempotency key is specified, the status code and body of the initial request are saved. Subsequent requests with the same key return the same result. This includes requests resulting in 500 errors.

Idempotency keys should be unique. The way you create them is up to you, but we suggest strings with enough entropy to avoid collisions. UUIDs are typically a good choice for this.

Idempotent requests are stored for 24 hours. Within a 24 hour period, the idempotency key and request information (body and method) are compared to the original request to ensure that the request is valid.

Idempotency keys are designed for use with POST requests. However, they can be used for PUT, PATCH, and DELETE requests as well, despite those requests being idempotent by definition.

Scopes

When creating an access_token, a scope may be specified to grant additional API privileges. By default, an app will be granted read-only access to an Emburse account. The following scopes are available:

Scope Description
(no scope) default By default, an app has read-only access to a company's:
  • Card descriptions
  • Transaction history
  • List of members
  • Accounting information
accountant An app with accountant privileges has read-only access to a company's Emburse account and, additionally, may:
  • Manage department, location, and label options
  • Update field values for transaction and card objects
admin An app with admin privileges has access to all spending, organizational, and accounting-related API endpoints and may:
  • Create and assign cards
  • Update allowances
  • Manage members
scim An app with scim privileges is authorized to use our SCIM API endpoints. Contact support if interested in completing a SCIM integration.

OAuth

If you are creating an app that will be used as a third-party integration by other Emburse clients, Emburse's API supports the OAuth2 protocol for web app authorization.

Only Emburse administrators and accountants may authorize third-party access to an Emburse account. After authorization is granted, the authorization may be revoked by any other administrator of the account.

View full OAuth documentation.

API Basics

Requests

For put and post requests, Emburse's API endpoints exclusively accept JSON data. When creating or updating API objects, be sure to set the request "Content-Type" header to "application/json".

Example Request
curl https://api.emburse.com/v1/categories -H "Authorization: Token ACCESS_TOKEN" -H "Content-Type: application/json" -X POST -d '{"name": "Fuel Expenses"}'

Pagination

For all Emburse API endpoints that return a list of API objects, the following GET parameters are supported:

GET Param Description
limit: default: 10 Maximum number of results to return. Max value: 1000
offset: default: 0 Starting index of the first object in the list.
created_after: Only objects created on or after this date/time are returned (ISO 8601 format).
created_before: Only objects created before this date/time are returned (ISO 8601 format).

In addition, all lists may be sorted using the ordering GET parameter. By default, lists are sorted using -created_at. For all endpoints, the following ordering values are supported:

Ordering Description
created_at Results will be sorted by creation date in ascending order. If using -created_at, results will be sorted by creation date in descending order.
Example Request
curl -H "Authorization: Token ACCESS_TOKEN" "https://api.emburse.com/v1/departments?offset=0&limit=100&ordering=-created_at"
Example Response
200 OK
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "397c5d89-9d81-412b-907b-ef44ac357a02",
      "url": "https://api.emburse.com/v1/...",
      "name": "Sales & Marketing",
      "created_at": "2016-02-06T10:02:33.312471Z"
    }
  ]
}

Cards

Emburse supports the creation of single-use and multi-use cards. Each card is associated with an allowance which specifies how much may be spent through the card.

Card Object

Field Description
id: Card UUID.
url: A fully-qualified URL for the card resource.
allowance: An allowance which specifies how much may be spent and contains the budget remaining on the card. Example: 
{
  "id": "1032d733-29ff-4388-905c-458292468aab",
  "url": "https://api.emburse.com/v1/...",
  "interval": "weekly",
  "amount": 500.0,
  "single_use": false,
  "transaction_limit": null,
  "daily_limit": 75.00,
  "start_time": null,
  "end_time": null,
  "scope": [],
  "balance": 500.0
}
description: Description displayed above card.
expiration: Card expiration date. Format: yyyy-mm-dd
is_virtual: Boolean specifying whether a card is virtual or physical.
last_four: Last 4 digits of the card number.
state: Card state may be one of the following values:
  • "unactivated"
  • "active"
  • "suspended"
  • "terminated"
A new physical card will start as unactivated. A new virtual card will start as active.
assigned_to: A member to whom this card is assigned. May be null if card has not been assigned. Example: 
{
  "id": "d99885ba-f9db-49ec-a097-6ef55eea824c",
  "url": "https://api.emburse.com/v1/...",
  "email": "joe@example.com",
  "first_name": "Joseph",
  "last_name": "Smith"
}
category: The category assigned to the card. May be null if category has not been set. Example: 
{
  "id": "ce0693b7-53dd-47cf-b145-dfaa6c9f7c00",
  "url": "https://api.emburse.com/v1/...",
  "code": null,
  "name": "Office Expenses"
}
department: The department assigned to the card. May be null if department has not been set. Example: 
{
  "id": "397c5d89-9d81-412b-907b-ef44ac357a02",
  "url": "https://api.emburse.com/v1/...",
  "name": "Sales & Marketing"
}
location: The location assigned to the card. May be null if location has not been set. Example: 
{
  "id": "4599b64a-4c3a-49d5-9794-798b4bbac093",
  "url": "https://api.emburse.com/v1/...",
  "name": "CA"
}
label: The label assigned to the card. May be null if label has not been set. Example: 
{
  "id": "6004f9eb-f3d5-44af-9367-813e359ba3ad",
  "url": "https://api.emburse.com/v1/...",
  "name": "Per Diem"
}
billing_address: Billing address of the card. Example: 
{
  "address_1": "123 Main St.",
  "address_2": "Suite 274",
  "city": "San Francisco",
  "state": "CA",
  "zip_code": "94110"
}
created_at: When this card was created (ISO 8601 format).
Example Card Object
{
  "id": "2316d331-e2d5-43f1-9c9d-8ca3a738df28",
  "url": "https://api.emburse.com/v1/...",
  "description": "Courier #125",
  "is_virtual": true,
  "last_four": "0632",
  "state": "active",
  "assigned_to": null,
  "category": {
    "id": "ce0693b7-53dd-47cf-b145-dfaa6c9f7c00",
    "url": "https://api.emburse.com/v1/...",
    "code": null,
    "name": "Office Expenses"
  },
  "department": null,
  "label": null,
  "location": null,
  "allowance": {
    "id": "1032d733-29ff-4388-905c-458292468aab",
    "url": "https://api.emburse.com/v1/...",
    "interval": null,
    "amount": 100.0,
    "single_use": false,
    "transaction_limit": null,
    "daily_limit": null,
    "start_time": null,
    "end_time": null,
    "scope": [],
    "balance": 100.0
  },
  "expiration": "2017-09-30",
  "billing_address": {
    "address_1": "123 Main St.",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "zip_code": "94104"
  },
  "created_at": "2016-08-19T23:56:22.020801Z"
}

List Cards

get /v1/cards

Retrieve a list of cards.

Filtering

Cards may be filtered using the following GET parameters.

GET Param Description
assigned_to: optional The ID of the member that a card is assigned to.
category: optional The ID of the category that a card is in.
department: optional The ID of the department that a card belongs to.
location: optional The ID of a location assigned to a card.
label: optional The ID of the label that a card is under.
state: optional Filter cards by state. Accepts a comma-separated list of valid card states:
  • "unactivated"
  • "active"
  • "suspended"
  • "terminated"
description: optional The card description.
Example Request
curl -H "Authorization: Token ACCESS_TOKEN" "https://api.emburse.com/v1/cards?assigned_to=d99885ba-f9db-49ec-a097-6ef55eea824c&state=active,suspended"

Get Card

get /v1/cards/:card_id

Retrieve a card by ID.

Example Request
curl -H "Authorization: Token ACCESS_TOKEN" "https://api.emburse.com/v1/cards/4fc5388c-ff13-46e2-b0f6-cd29e34e72b2"

Create Card

post /v1/cards

Create a new card. New virtual cards are pre-activated and are ready for immediate use. For physical card issuance, please contact support to enable card ordering via API.

In addition to the optional assigned_to, category, label, and department fields within the card object, the following fields may be used.

Field Description
allowance: required An allowance with the card's initial spending restrictions. An allowance object will be created from these initial values. Example: 
{
  "interval": null,
  "amount": 500.00,
  "transaction_limit": 75.00
}
description: required A short description to be displayed above the card.
is_virtual: required Boolean specifying whether to create a virtual card or order a physical card. If is_virtual is set to false, a valid shipping_address must also be provided.
shipping_address: required for physical cards If ordering a physical card, a shipping address is required. This field should be an object containing the following fields. Example: 
{
  "attn": "Emburse",
  "address_1": "548 Market St.",
  "address_2": "Suite 27197",
  "city": "San Francisco",
  "state": "CA",
  "zip_code": "94104",
}
billing_name: optional The name to be printed on the card. Defaults to the card description if unset. Maximum length of 40 characters.
billing_address: optional A custom billing address for this card. If omitted, the account's default billing address will be used. Example: 
{
  "address_1": "548 Market St.",
  "address_2": "Suite 27197",
  "city": "San Francisco",
  "state": "CA",
  "zip_code": "94104",
}
Example Request
curl "https://api.emburse.com/v1/cards" -H "Authorization: Token ACCESS_TOKEN" -H "Content-Type: application/json" -X POST -d '
{
  "allowance": {
    "interval": null,
    "amount": 500.00,
    "transaction_limit": 75.00
  },
  "description": "Vendor #125",
  "is_virtual": true
}'
Example Response
201 Created
{
  "id": "9d79e33a-fec9-4ccd-893b-01d2ed3e1105",
  "url": "https://api.emburse.com/v1/...",
  "description": "Vendor #125",
  "is_virtual": true,
  "last_four": "8923",
  "state": "active",
  "assigned_to": null,
  "category": null,
  "department": null,
  "label": null,
  "location": null,
  "allowance": {
    "id": "ce93d83a-8a43-439d-9f5b-cc6ed89ecf89",
    "url": "https://api.emburse.com/v1/...",
    "interval": null,
    "amount": 500,
    "single_use": false,
    "transaction_limit": 75,
    "daily_limit": null,
    "start_time": null,
    "end_time": null,
    "scope": [],
    "balance": 500
  },
  "expiration": "2019-08-31",
  "billing_address": {
    "address_1": "123 Main St.",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "zip_code": "94104"
  },
  "created_at": "2016-08-26T06:54:44.235115Z"
}

Update Card

put /v1/cards/:card_id

Update an existing card. The following fields may be updated once a card has been created. A card's allowance may also be updated via the allowance API endpoint. All card updates are reflected immediately.

Field Description
assigned_to: optional Object with member ID or null.
category: optional Object with category ID or null.
department: optional Object with department ID or null.
description: optional Description shown above card.
label: optional Object with label ID or null.
state: optional Card state may be set to one the following values:
  • "active"
  • "suspended"
  • "terminated"
Once a card is terminated, its state may no longer be updated. Physical cards which start as unactivated must be activated by the card assignee and cannot be activated via the API. A card must be active before it may be suspended.
billing_address: optional Object or null.

Add, update, or remove a custom billing address for this card. If null, the account's default billing address will be used. Example: 
{
  "address_1": "548 Market St.",
  "address_2": "Suite 27197",
  "city": "San Francisco",
  "state": "CA",
  "zip_code": "94104",
}
Suspending a Card
curl https://api.emburse.com/v1/cards/CARD_ID -H "Authorization: Token ACCESS_TOKEN" -H "Content-Type: application/json" -X PUT -d '{"state": "suspended"}'
Adding a Label
curl https://api.emburse.com/v1/cards/CARD_ID -H "Authorization: Token ACCESS_TOKEN" -H "Content-Type: application/json" -X PUT -d '{"label": {"id": "6004f9eb-f3d5-44af-9367-813e359ba3ad"}}'
Removing a Category
curl https://api.emburse.com/v1/cards/CARD_ID -H "Authorization: Token ACCESS_TOKEN" -H "Content-Type: application/json" -X PUT -d '{"category": null}'

Delete Card

delete /v1/cards/:card_id

Delete an existing card. A deleted card will automatically be terminated. A transaction associated with a deleted card will continue to reference the deleted card within its card field.

Example Request
curl https://api.emburse.com/v1/cards/CARD_ID -H "Authorization: Token ACCESS_TOKEN" -H "Content-Type: application/json" -X DELETE
Example Response
204 No Content

Allowances

The budget on a card is described by its allowance. An allowance object both defines a card's spending restrictions and contains its remaining balance.

Allowance Object

Field Description
id: Allowance UUID.
url: A fully-qualified URL for the allowance resource.
amount: Decimal representing budget assigned to card.
interval: How often this budget is reset. May be one of the following values:
  • null – never reset
  • "daily" – reset daily
  • "weekly" – reset weekly
  • "monthly" – reset monthly
balance: Remaining amount that may be spent.
daily_limit: Additional restriction on much may be spent each day. May be null if no additional restriction has been set.
transaction_limit: Additional restriction on a transaction's maximum amount. May be null if no additional restriction has been set.
single_use: Boolean is true if allowance may only be used for a single transaction after which the allowance's card will be suspended.
start_time: Time (ISO 8601 format) before which transactions will be declined. May be null if no additional restriction has been set.
end_time: Time (ISO 8601 format) after which transactions will be declined and card will be suspended. May be null if no additional restriction has been set.
scope: An array of integers limiting the categories of merchants that may be paid. By default, scope is set to [ ] and no merchant restrictions are set. If one or more values are present, only merchants within those scope categories may authorize transactions. Example scope values:
  • [4] – Gas Stations
  • [5, 6] – Restaurants & Ground Transportation
  • [5542] – Automated Fuel Dispensers
View a full list of supported merchant categories. The scope field may contain up to 10 merchant category values.
created_at: When this allowance was created (ISO 8601 format).
Example Allowance Object
{
  "id": "22f6fe8f-ff91-473c-86ef-a6e8480508bb",
  "url": "https://api.emburse.com/v1/...",
  "interval": "weekly",
  "amount": 500.0,
  "single_use": false,
  "transaction_limit": 150.0,
  "daily_limit": null,
  "start_time": null,
  "end_time": "2016-08-28T00:00:00Z",
  "scope": [6],
  "balance": 437.27,
  "created_at": "2016-08-20T00:24:46.609518Z"
}

Get Allowance

get /v1/allowances/:allowance_id

Retrieve an allowance by ID.

Example Request
curl -H "Authorization: Token ACCESS_TOKEN" "https://api.emburse.com/v1/allowances/22f6fe8f-ff91-473c-86ef-a6e8480508bb"

Update Allowance

put /v1/allowances/:allowance_id

Update an existing allowance.

Field Description
amount: optional Decimal with a value greater than or equal to 0.0.
interval: optional String representing how often the budget is reset. May be null or one of the following values:
  • "daily"
  • "weekly"
  • "monthly"
reset: optional By default, the balance is not reset each time the allowance amount is updated. Set reset to true if the balance on a card should be reset to its initial amount. May only be used if interval is set to null.
daily_limit: optional Decimal with a value greater than 0.0 or null.
transaction_limit: optional Decimal with a value greater than 0.0 or null.
single_use: optional Boolean for whether an allowance may only be used once before card is suspended.
start_time: optional Time before which all transactions should be declined (ISO 8601 format) or null.
end_time: optional Time after which all transactions should be declined (ISO 8601 format) or null.
scope: optional An array of integers representing merchant categories. Array may be empty and may contain at most 10 values.
Adjusting a Budget
curl https://api.emburse.com/v1/allowances/ALLOWANCE_ID -H "Authorization: Token ACCESS_TOKEN" -H "Content-Type: application/json" -X PUT -d '{"amount": 100.0}'
Resetting a Balance
curl https://api.emburse.com/v1/allowances/ALLOWANCE_ID -H "Authorization: Token ACCESS_TOKEN" -H "Content-Type: application/json" -X PUT -d '{"amount": 100.0, "reset": true}'
Adding Merchant Restrictions
curl https://api.emburse.com/v1/allowances/ALLOWANCE_ID -H "Authorization: Token ACCESS_TOKEN" -H "Content-Type: application/json" -X PUT -d '{"scope": [5,6]}'

Shared Links

Emburse supports the creation of publicly accessible shared links for a given card. Any user with the shared link can access details about the card.

Admin Scope Required
Unlike other API endpoints, both read and write access to shared link endpoints require use of the admin scope.

Shared Link Object

Field Description
id: Shared Link UUID.
url: A fully-qualified URL for the shared link.
link: Anyone with this link can view the shared card.
card: The card with which the shared link is associated.
recipient: The recipient this shared link has been sent to. This key will not be present if the shared link has not been emailed. Example: 
{
  "name": "John Johnson",
  "email": "johnj@example.com"
}
passphrase_fields: The passphrase fields set for this shared link. This key will not be present if no passphrase fields have been set. Example: 
[{
  "name": "Birthday",
  "value": "1999-12-31",
  "type": "date"
}, {
  "name": "Mother′s Maiden Name",
  "value": "Smith",
  "type": "text"
}]
hide_balance: Boolean specifying whether balance and budget information is hidden when viewing the shared card.
last_viewed_at: Time (ISO 8601 format) when the card within the shared link was last viewed. May be null if never viewed.
Example Shared Link Object
{
  "id": "2316d331-e2d5-43f1-9c9d-8ca3a738df28",
  "url": "https://api.emburse.com/v1/...",
  "link": "https://app.emburse.com/c/2316d331...",
  "card": {
    "id": "ce0693b7-53dd-47cf-b145-dfaa6c9f7c00"
  },
  "recipient": {
    "name": "John Johnson",
    "email": "johnj@example.com"
  },
  "passphrase_fields": [{
    "name": "Birthday",
    "value": "1999-12-31",
    "type": "date"
    }, {
    "name": "Mother′s Maiden Name",
    "value": "Smith",
    "type": "text"
  }],
  "hide_balance": false,
  "last_viewed_at": null
}

List Shared Links

get /v1/shared-links

Retrieve a list of shared links.

Filtering

Shared links may be filtered using the following GET parameters.

GET Param Description
card: optional The ID of the card for this shared link.
Example Request
curl -H "Authorization: Token ACCESS_TOKEN" "https://api.emburse.com/v1/shared-links?card=1032d733-29ff-4388-905c-458292468aab

Get Shared Link

get /v1/shared-links/:shared_link_id

Retrieve a shared link by ID.

Example Request
curl -H "Authorization: Token ACCESS_TOKEN" "https://api.emburse.com/v1/shared-links/4fc5388c-ff13-46e2-b0f6-cd29e34e72b2"

Create Shared Link

post /v1/shared-links

Create a new shared link.

Field Description
card: required Object with card ID. The card for which you want to create a shared link.
recipient: optional The recipient this shared link will be sent to represented as an object with name, email, and message properties. The notify property can be used to enable/disable sending of email notification to the recipient.

Example:

{
  "name": "John Johnson",
  "email": "johnj@example.com",
  "message": "Spend it wisely..."
}
Field descriptions:
  • "name" – Name of recipient
  • "email" – Email address of recipient
  • "message" – Optional custom message
  • "notify" – Set to false to omit email notification
passphrase_fields: optional The passphrase fields to set for this shared link. Array of objects with name, value and type fields or empty array ([]).

The value for type should be either "text" or "date". Dates should be formatted as YYYY-MM-DD. Example: 
[{
  "name": "Birthday",
  "value": "1999-12-31",
  "type": "date"
}, {
  "name": "Mother′s Maiden Name",
  "value": "Smith",
  "type": "text"
}]
hide_balance: default: false Set to true to hide balance and budget information when the shared card is viewed.
Example Request
curl "https://api.emburse.com/v1/shared-links" -H "Authorization: Token ACCESS_TOKEN" -H "Content-Type: application/json" -X POST -d '
{
  "card": {
    "id": "ce0693b7-53dd-47cf-b145-dfaa6c9f7c00"
  },
  "recipient": {
    "name": "John Johnson",
    "email": "johnj@example.com",
    "message": "Spend it wisely...",
    "notify": true
  },
  "passphrase_fields": [{
    "name": "Birthday",
    "value": "1999-12-31",
    "type": "date"
    }, {
    "name": "Mother′s Maiden Name",
    "value": "Smith",
    "type": "text"
  }]
}'
Example Response
201 Created
{
  "id": "2316d331-e2d5-43f1-9c9d-8ca3a738df28",
  "url": "https://api.emburse.com/v1/...",
  "link": "https://app.emburse.com/c/2316d331...",
  "card": {
    "id": "ce0693b7-53dd-47cf-b145-dfaa6c9f7c00"
  },
  "recipient": {
    "name": "John Johnson",
    "email": "johnj@example.com"
  },
  "passphrase_fields": [{
    "name": "Birthday",
    "value": "1999-12-31",
    "type": "date"
    }, {
    "name": "Mother′s Maiden Name",
    "value": "Smith",
    "type": "text"
  }],
  "hide_balance": false,
  "last_viewed_at": null
}

Update Shared Link

put /v1/shared-links/:shared_link_id

Update an existing shared link. The following fields may be updated once a shared link has been created.

Field Description
recipient: The recipient this shared link will be sent to. A new recipient will overwrite the previous recipient, and a new email will be sent if notify is true (or if field is absent).

Please reference the POST documentation for details about the recipient field.
passphrase_fields: The passphrase fields to set for this shared link. Array of objects with name, value and type fields or empty array ([]).

The value for type should be either "text" or "date". Dates should be formatted as YYYY-MM-DD. Example: 
[{
  "name": "Birthday",
  "value": "1999-12-31",
  "type": "date"
}, {
  "name": "Mother′s Maiden Name",
  "value": "Smith",
  "type": "text"
}]
hide_balance: Set to true to hide balance and budget information when the shared card is viewed.
Adding a Recipient
curl https://api.emburse.com/v1/shared-links/SHARED_LINK_ID -H "Authorization: Token ACCESS_TOKEN" -H "Content-Type: application/json" -X PUT -d '{ "recipient": { "email": "john@example.com" } }'

Delete Shared Link

delete /v1/shared-links/:shared_link_id

Delete an existing shared link. The backing card associated with the shared link will not be deleted.

Example Request
curl https://api.emburse.com/v1/shared-links/SHARED_LINK_ID -H "Authorization: Token ACCESS_TOKEN" -H "Content-Type: application/json" -X DELETE
Example Response
204 No Content

Transactions

A transaction object is created for each card purchase or bank transfer. A transaction will often start in a pending state before it becomes completed several days later. During this time, the transaction amount may change. Transactions that are declined will also be included within the returned list.

Bank Feed Application Developers
For immutable transactions created once transactions are posted, please take a look at our bank statements endpoint. In contrast to statement_line objects, the transaction objects in this section are mutable and are created based on when transactions are authorized.

Transaction Object

Field Description
id: Transaction UUID.
url: A fully-qualified URL for the transaction resource.
amount: Transaction amount will be:
  • Negative for debits
  • Positive for credits
The amount will be zero for canceled transactions. The amount will contain the original requested purchase amount for declined transactions.
foreign_amount: Equivalent to amount above, except in original transaction currency, if applicable. Otherwise null.
foreign_currency_code: Foreign transaction currency code in ISO 4217 format, if applicable. Otherwise null.
state: Transaction state may be one of the following values:
  • "pending"
  • "completed"
  • "declined"
A pending transaction will become completed within 7 days and usually within 24 hours.
card: The card used for this transaction. May be null if transaction does not represent a card purchase. Example: 
{
  "id": "90ab2860-768f-4af8-8638-0a0bcdfdbb90",
  "url": "https://api.emburse.com/v1/...",
  "state": "active",
  "description": "Courier #781",
  "last_four": "7781"
}
member: The member responsible for this transaction. May be null if transaction is not assignable. Example: 
{
  "id": "c80e0483-1e03-4387-95b4-b408b10f3e1d",
  "url": "https://api.emburse.com/v1/",
  "email": "john@example.com",
  "first_name": "John",
  "last_name": "Smith"
}
category: The category assigned to the transaction. May be null if category has not been set. Example: 
{
  "id": "ce0693b7-53dd-47cf-b145-dfaa6c9f7c00",
  "url": "https://api.emburse.com/v1/...",
  "code": null,
  "name": "Office Expenses"
}
department: The department assigned to the transaction. May be null if department has not been set. Example: 
{
  "id": "397c5d89-9d81-412b-907b-ef44ac357a02",
  "url": "https://api.emburse.com/v1/...",
  "name": "Sales & Marketing"
}
location: The location assigned to the transaction. May be null if location has not been set. Example: 
{
  "id": "4599b64a-4c3a-49d5-9794-798b4bbac093",
  "url": "https://api.emburse.com/v1/...",
  "name": "CA"
}
label: The label assigned to the transaction. May be null if label has not been set. Example: 
{
  "id": "6004f9eb-f3d5-44af-9367-813e359ba3ad",
  "url": "https://api.emburse.com/v1/...",
  "name": "Per Diem"
}
receipt: A user-uploaded receipt for the transaction. May be null if no receipt exists or have missing fields if the receipt has been lost. Example: 
{
  "url": "https://app.emburse.com/...",
  "filename": "receipt.pdf"
}
If the receipt has been lost: 
{
  "lost": true
}
Field descriptions:
  • "url" – Receipt location.
  • "filename" – Original receipt filename.
  • "lost" – True if receipt has been lost.
note: A user-provided note about the transaction. May be blank.
bank_account: optional If the transaction represents a bank transfer, a bank_account describing the funding source will be provided. Example: 
{
  "description": "Emburse Checking Account",
  "name": "EMBURSE INC",
  "number": "8432"
}
Field descriptions:
  • "description" – User-provided description.
  • "name" – Name on account.
  • "number" – Last four digits of account number.
merchant: optional If the transaction represents a purchase, merchant details will be provided. Example: 
{
  "mid": 526559301139368,
  "mcc": 7399,
  "name": "THE UPS STORE 4592",
  "address": "660 4TH ST",
  "city": "SAN FRANCISCO",
  "state": "CA",
  "zip": "94107",
  "country": "US"
}
Field descriptions:
  • "mid" – Merchant ID (Int64).
  • "mcc" – Merchant category code.
  • "name" – Merchant name.
  • "address" – Merchant address.
  • "city" – Address city.
  • "state" – Address state.
  • "zip" – Address zip code.
  • "country" – Address country.
None of these fields are guaranteed to exist. Each field may be set to null.
requisition: optional If the transaction is associated with a requisition, also known as a pre-approval, the details of that requisition will be provided. Example: 

{
  "id": "8f668a13-9507-4567-86d5-498bc2609927",
  "status": "approved",
  "description": "Office Supplies",
  "amount": 500.0
}
Field descriptions:
  • "id" – Requisition UUID
  • "description" – A user-provided description of the purchase being requested.
  • "amount" – The amount requested for the requisition.
  • "status" – Status of the requisition. May be one of the following values:
    • "pending" – pending approval
    • "denied" – request denied
    • "approved" – request approved
response_code: optional If the transaction was declined, an integer response_code will be included to provide details regarding the reason for the decline. Response code descriptions are included below.
time: When this transaction was authorized on the card networks (ISO 8601 format).
posted_at: When this transaction posted (ISO 8601 format). May be null if transaction is still pending, was declined, or was canceled.
created_at: When this transaction was created (ISO 8601 format).

Response Codes

For declined transactions, a response_code is included that provides details regarding the reason for the decline.

Code Description
0 Transaction approved.
1000 Transaction declined. Reason unavailable.
1101 Insufficient funds in business account.
1201 Card unactivated.
1202 Card suspended.
1203 Card expired.
1301 Invalid expiration date.
1302 Invalid PIN.
1303 Invalid CVV.
1304 Invalid ZIP Code.
1501 Unfulfilled allowance constraints.
1502 Allowance amount exceeded.
1503 Allowance transaction limit exceeded.
1701 Risk monitoring decline.
1702 Cash withdrawal denied.
Example Card Purchase
{
  "id": "0849b836-bc20-4a83-8218-e50f8c9e56c4",
  "url": "https://api.emburse.com/v1/...",
  "amount": -119.21,
  "foreign_amount": null,
  "foreign_currency_code": null,
  "state": "pending",
  "merchant": {
    "mid": 445201094999,
    "mcc": 7311,
    "name": "ADROLL",
    "address": null,
    "city": "SAN FRANCISCO",
    "state": "CA",
    "zip": "94103",
    "country": "US"
  },
  "card": {
    "id": "c195f95f-42ea-42b9-bf62-25ea0995a9a4",
    "url": "https://api.emburse.com/v1/...",
    "state": "active",
    "description": "Advertising",
    "last_four": "7640"
  },
  "member": {
    "id": "d8ef8d51-8c48-4da7-8758-a7b578a4d360",
    "url": "https://api.emburse.com/v1/...",
    "email": "justin@example.com",
    "first_name": "Justin",
    "last_name": "Jones"
  },
  "category": {
    "id": "c66b60c5-449c-4482-ac66-e3c5557f4b49",
    "url": "https://api.emburse.com/v1/...",
    "code": null,
    "name": "Sales & Marketing"
  },
  "requisition":{
    "id": "8f668a13-9507-4567-86d5-498bc2609927",
    "status": "approved",
    "description": "Ad Expenditure",
    "amount": 200.0
  },
  "department": null,
  "label": null,
  "location": null,
  "receipt": null,
  "note": "",
  "time": "2016-08-19T04:02:05Z",
  "posted_at": null,
  "created_at": "2016-08-19T04:02:07.016369Z"
}
Example Bank Transfer
{
  "id": "3575ab44-3632-456f-9e41-05181b98a599",
  "url": "https://api.emburse.com/v1/...",
  "amount": 1944.27,
  "state": "completed",
  "bank_account": {
    "description": "Emburse Checking Account",
    "name": "EMBURSE INC",
    "number": "8432"
  },
  "card": null,
  "member": null,
  "category": null,
  "department": null,
  "label": null,
  "location": null,
  "receipt": null,
  "note": "",
  "time": "2016-08-13T00:00:07Z",
  "posted_at": "2016-08-15T00:00:09Z",
  "created_at": "2016-08-13T00:00:07.778920Z"
}
Example Refund
{
  "id": "a15ddc03-d11c-42c5-a3aa-8348f2012e84",
  "url": "https://api.emburse.com/v1/...",
  "amount": 359.39,
  "state": "completed",
  "merchant": {
    "mid": 185119000762203,
    "mcc": 6411,
    "name": "Amazon web services",
    "address": "330 Central Ave. St.",
    "city": "St. Petersburg",
    "state": "CA",
    "zip": "33705",
    "country": "US"
  },
  "card": {
    "id": "92a41d94-a7d1-484b-b0e8-841df5a87af0",
    "url": "https://api.emburse.com/v1/...",
    "state": "active",
    "description": "Infrastructure",
    "last_four": "3319"
  },
  "member": null,
  "category": {
    "id": "a4d1b9f5-0f2d-4747-bb67-f1f3b1c588d2",
    "url": "https://api.emburse.com/v1/...",
    "code": null,
    "name": "Web Infrastructure"
  },
  "department": null,
  "label": null,
  "location": null,
  "receipt": null,
  "note": "",
  "time": "2016-05-11T20:01:03Z",
  "posted_at": "2016-05-24T17:38:01Z",
  "created_at": "2016-05-11T20:01:04.287031Z"
}

List Transactions

get /v1/transactions

Retrieve a list of transactions.

Filtering

Transactions may be filtered using the standard pagination filters as well as using the following GET parameters.

GET Param Description
before: optional Filters using time for transactions authorized before this date/time (ISO 8601 format).
after: optional Filters using time for transactions authorized on or after this date/time (ISO 8601 format).
card: optional The ID of a card associated with a transaction.
member: optional The ID of a member responsible for a transaction.
category: optional The ID of a category assigned to a transaction.
department: optional The ID of a department assigned to a transaction.
location: optional The ID of a location assigned to a transaction.
label: optional The ID of a label assigned to a transaction.

Ordering

By default, transactions are sorted using -created_at and are returned in reverse chronological order based on when our system receives transactions. You may also sort transactions by time to order transactions by authorization time.

Ordering Description
created_at Results will be sorted in chronological order using the created_at field. If using -created_at, results will be sorted by creation date in descending order.
time Results will be sorted in chronological order using the time field. If using -time, results will be sorted in reverse chronological order.
Example Request
curl -H "Authorization: Token ACCESS_TOKEN" "https://api.emburse.com/v1/transactions?card=c195f95f-42ea-42b9-bf62-25ea0995a9a4"

Get Transaction

get /v1/transactions/:transaction_id

Retrieve a transaction by ID.

Example Request
curl -H "Authorization: Token ACCESS_TOKEN" "https://api.emburse.com/v1/transactions/0849b836-bc20-4a83-8218-e50f8c9e56c4"

Update Transaction

put /v1/transactions/:transaction_id

The accounting-related fields of a transaction may be updated.

FieldDescription
category: optional Object with category ID or null.
department: optional Object with department ID or null.
label: optional Object with label ID or null.
note: optional String of up to 1000 characters. May be blank.
Example Request
curl "https://api.emburse.com/v1/transactions/TRANSACTION_ID" -H "Authorization: Token ACCESS_TOKEN" -H "Content-Type: application/json" -X PUT -d '{"category": {"id": "a4d1b9f5-0f2d-4747-bb67-f1f3b1c588d2"}}'

Requisitions

Requisitions represent purchase requests that are initiated by members and are approved by admins or reviewers.

Compatibility Limitations
Due to partner limitation, requisitions may only be created for cards issuing through the VISA card network.

Requisition Object

Field Description
id: Requisition UUID.
amount: The amount requested for the requisition.
approved_at: Time (ISO 8601 format) requisition was approved or null if the requisition is not approved.
card: The card used for fulfilling the requisition. May be null if requisition has not been approved. Example: 
{
  "id": "90ab2860-768f-4af8-8638-0a0bcdfdbb90",
  "url": "https://api.emburse.com/v1/...",
  "state": "active",
  "description": "Courier #781",
  "last_four": "7781"
}
category: The category assigned to the requisition. May be null if category has not been set. Example: 
{
  "id": "ce0693b7-53dd-47cf-b145-dfaa6c9f7c00",
  "url": "https://api.emburse.com/v1/...",
  "code": null,
  "name": "Office Expenses"
}
created_at: When this requisition was created (ISO 8601 format).
department: The department assigned to the requisition. May be null if department has not been set. Example: 
{
  "id": "397c5d89-9d81-412b-907b-ef44ac357a02",
  "url": "https://api.emburse.com/v1/...",
  "name": "Sales & Marketing"
}
description: A user-provided description of the purchase being requested.
end_time: Time (ISO 8601 format) before which purchase must be made. May be null if no restriction is set.
label: The label assigned to the requisition. May be null if label has not been set. Example: 
{
  "id": "6004f9eb-f3d5-44af-9367-813e359ba3ad",
  "url": "https://api.emburse.com/v1/...",
  "name": "Per Diem"
}
location: The location assigned to the requisition. May be null if location has not been set. Example: 
{
  "id": "4599b64a-4c3a-49d5-9794-798b4bbac093",
  "url": "https://api.emburse.com/v1/...",
  "name": "CA"
}
member: The member who created the requisition. Example: 
{
  "id": "c80e0483-1e03-4387-95b4-b408b10f3e1d",
  "url": "https://api.emburse.com/v1/",
  "email": "john@example.com",
  "first_name": "John",
  "last_name": "Smith"
}
note: A user-provided note about the purchase being requested.
reviewed_by: The member who last approved or denied a requisition.
status: Status of the requisition. May be one of the following values:
  • "pending" – pending approval
  • "denied" – request denied
  • "approved" – request approved
url: A fully-qualified URL for the requisition resource.

Example requisition object:

{
  "id": "8368c4bf-321a-4b0c-bde9-53b96943c8ad",
  "amount": 15000.0,
  "approved_at": "2020-09-15T21:08:34.338755Z",
  "card": {
    "id": "d69fe542-00b8-4cae-aa44-14e3fc8c23c6",
    "url": "https://api.emburse.com/v1/...",
    "state": "active",
    "description": "Event Catering",
    "last_four": "2094"
  },
  "category": null,
  "created_at": "2020-09-15T21:08:27.645173Z",
  "department": null,
  "description": "Food and Drinks",
  "end_time": "2021-01-01T04:59:59Z",
  "label": null,
  "location": null,
  "member": {
    "id": "c80e0483-1e03-4387-95b4-b408b10f3e1d",
    "url": "https://api.emburse.com/v1/...",
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe"
  },
  "note": null,
  "reviewed_by": {
    "id": "c80e0483-1e03-4387-95b4-b408b10f3e1d",
    "url": "https://api.emburse.com/v1/...",
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe"
  },
  "status": "approved",
  "url": "https://api.emburse.com/v1/...",
}

List Requisitions

get /v1/requisitions

Retrieve a list of requisitions.

Filtering

Requisitions may be filtered using the following GET parameters.

GET Param Description
card: optional The ID of the card for a requisition.
member: optional The ID of the member for a requisition.
status: optional The status of a requisition. Options are:
  • pending
  • approved
  • denied
Example Request
curl -H "Authorization: Token ACCESS_TOKEN" "https://api.emburse.com/v1/requisitions"

Get Requisition

get /v1/requisitions/:requisition_id

Retrieve a requisition by ID.

Example Request
curl -H "Authorization: Token ACCESS_TOKEN" "https://api.emburse.com/v1/requisitions/6c011965-94dd-4721-84ea-2a7d1eedcb9e"

Company

The company object provides details about the company that has granted authorization.

Company Object

Field Description
id: Company UUID.
name: Company name.
website: Company website.
shipping_address: The company's preferred shipping_address. Example: 
{
  "id": "1535a7d0-6797-46b3-8b7a-593e59d52851",
  "url": "https://api.emburse.com/v1/...",
  "address_1": "123 Main St.",
  "address_2": "",
  "city": "San Francisco",
  "state": "CA",
  "zip_code": "94104"
}
created_at: When this company was created (ISO 8601 format).
Example Company Object
{
  "id": "95e6d004-7907-415e-a373-91e9e10b4a36",
  "name": "Emburse Inc.",
  "website": "https://emburse.com/",
  
  "shipping_address": {
    "id": "1535a7d0-6797-46b3-8b7a-593e59d52851",
    "url": "https://api.emburse.com/v1/...",
    "address_1": "123 Main St.",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "zip_code": "94104"
  },
  "created_at": "2015-08-27T14:43:02.346387Z"
}

Get Company

get /v1/company

Retrieve details about the company that has granted app authorization.

Example Request
curl -H "Authorization: Token ACCESS_TOKEN" "https://api.emburse.com/v1/company"

Members

Members are people within a company who may be assigned cards. A physical card must be assigned to a member before the card may be activated. The full 16-digit card numbers for virtual cards are accessible by card assignees once logged in to Emburse.

Transactions on cards assigned to a member are automatically associated within that member. In addition, card assignees receive transaction decline messages and suspicious activity alerts.

Member Object

Field Description
id: Member UUID.
url: A fully-qualified URL for the member resource.
first_name: Member's first name.
last_name: Member's last name.
role: Member role may be one of the following values:
  • "member"
  • "reviewer"
  • "accountant"
  • "admin"
code: Field for storing employee ID. May be a unique numeric string or null.
email: Member's email address.
is_active: Indicates whether the member is active (true) or inactive (false)
created_at: When this member was created (ISO 8601 format).
Example Member Object
{
  "id": "b59863cd-75cb-4c14-b396-0cf25d9b173f",
  "url": "https://api.emburse.com/...",
  "email": "sarah@example.com",
  "first_name": "Sarah",
  "last_name": "Smith",
  "role": "member",
  "code": "0001",
  "is_active": true,
  "created_at": "2015-09-02T13:26:36.727444Z"
}

List Members

get /v1/members

Retrieve a list of members.

Filtering

Members may be filtered using the following GET parameters.

GET Param Description
email: optional Member email address. Case-insensitive search requires exact match.
is_active: optional When this parameter is not specified, both active and inactive members are listed together. Setting this parameter to true will yield active members and setting it to false will yield inactive members.
created_after: optional To list members created after a specific time, supply this parameter (ISO 8601 timestamp).
created_before: optional To list members created before a specific time, supply this parameter (ISO 8601 timestamp).
Example Request
curl -H "Authorization: Token ACCESS_TOKEN" "https://api.emburse.com/v1/members?created_after=2016-05-11T00:00:00Z"

Get Member

get /v1/members/:member_id

Retrieve a member by ID.

Example Request
curl -H "Authorization: Token ACCESS_TOKEN" "https://api.emburse.com/v1/members/b59863cd-75cb-4c14-b396-0cf25d9b173f"

Create Member

post /v1/members

Create a new member who will be invited to set a password for an account and review card transactions online. A first_name, last_name, and email address are required when creating a new member. Additionally, a member's role may be set to one of the following values:

  • "member"
  • "reviewer"

Within a company's account, member email addresses must be unique.

Example Request
curl "https://api.emburse.com/v1/members" -H "Authorization: Token ACCESS_TOKEN" -H "Content-Type: application/json" -X POST -d '{"first_name": "John", "last_name": "Jameson", "email": "john@example.com"}'

Update Member

put /v1/members/:member_id

The first_name, last_name, is_active, and code of a member may be updated. Additionally, a member's role may be set to one of the following values:

  • "member"
  • "reviewer"

A member's email address may not be changed.

Deactivating the member by setting is_active to false will:

  • Set the member's role to "member".
  • Terminate the member's cards
  • Deny any pending requisitions submitted by the member
  • Unshare any cards shared with this member
  • Resolve any out-of-policy expenses
  • Prevent this member from being part of all Emburse functionality, including logging in
Reactivating the member by setting is_active to true will:
  • Restore this member's ability to participate in Emburse functionality
Note: the side effects of setting is_active to false are not undone by setting is_active back to true.

Example Request
curl "https://api.emburse.com/v1/members/MEMBER_ID" -H "Authorization: Token ACCESS_TOKEN" -H "Content-Type: application/json" -X PUT -d '{"first_name": "Jonathan", "code": "0002"}'

Delete Member

delete /v1/members/:member_id

Deleting a member is equivalent to deactivating a member with the added effect of removing the member from lists returned via our API. Any transactions or cards associated with a deleted member will continue to reference the deleted member within the member field.

Example Request
curl "https://api.emburse.com/v1/cards/CARD_ID" -H "Authorization: Token ACCESS_TOKEN" -H "Content-Type: application/json" -X DELETE
Example Response
204 No Content

Accounts

All card transactions and bank transfers debit from and deposit to the same account. A bank balance is provided to track how much is available to spend and how much is currently residing within an account.

Account Object

Field Description
id: Account UUID.
url: A fully-qualified URL for the account resource.
name: Account name.
number: String representing 12-digit account number.
ledger_balance: Amount of money currently residing within the Emburse account.
available_balance: Amount of money that may be spent after taking in consideration authorization holds and pending transactions.
available_credit: If the business has been extended a line of credit, the credit limit is added to the available_balance for this value.
pending_credits: Amount of money from transfers in transit to Emburse account.
credit_limit: Line of credit amount. Set to $0 for prefunded accounts.
funding_source: Bank account from which funds are drawn represented as an object with a name and is_verified. May be null if no bank account has been set. Example: 
{
  "name": "Checking - 1020",
  "is_verified": true
}
Field descriptions:
  • "name" – Name of bank account
  • "is_verified" – true if funds may be drawn
created_at: When this account was created (ISO 8601 format).
Example Account Object
{
  "id": "64745919-0caf-4e6b-8e63-17e7a0d1035e",
  "url": "https://api.emburse.com/v1/...",
  "name": "Emburse Account for Acme Inc.",
  "number": "880307390512",
  "ledger_balance": 1258.43,
  "available_balance": 872.35,
  "available_credit": 872.35,
  "pending_credits": 0,
  "credit_limit": 0,
  "funding_source": {
    "name": "Checking - 1020",
    "is_verified": true
  },
  "created_at": "2015-09-12T17:05:03.058556Z"
}

List Accounts

get /v1/accounts

Retrieve a list of accounts. Because each company currently only has one account, a list with one account will always be returned. Regardless, we recommend implementing solutions that support having multiple accounts per company. Emburse will soon be adding sub-accounts to enable having a seperate bank statement for each card or member.

Example Request
curl -H "Authorization: Token ACCESS_TOKEN" "https://api.emburse.com/v1/accounts"
Example Response
200 OK
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "64745919-0caf-4e6b-8e63-17e7a0d1035e",
      "url": "https://api.emburse.com/v1/...",
      "name": "Emburse Account for Acme Inc.",
      "number": "880307390512",
      "ledger_balance": 1258.43,
      "available_balance": 872.35,
      "available_credit": 872.35,
      "pending_credits": 0,
      "credit_limit": 0,
      "funding_source": {
        "name": "Checking - 1020",
        "is_verified": true
      },
      "created_at": "2015-09-12T17:05:03.058556Z"
    }
  ]
}

Get Account

get /v1/accounts/:account_id

Retrieve an account by ID.

Example Request
curl -H "Authorization: Token ACCESS_TOKEN" "https://api.emburse.com/v1/accounts/64745919-0caf-4e6b-8e63-17e7a0d1035e"

Statements

Bank statements contain posted transactions for an account. Bank statements may either be exported as downloadable files or they may be queried via an API endpoint that returns a list of statement_line objects.

Supported Formats

Format Description
csv CSV file will include a header in the first row describing the values of each column.
ofx The OFX file format is supported by most accounting services for importing bank statements.
pdf A human-readable PDF for manual audits.

Statement Line Object

Field Description
id: Statement line UUID.
url: A fully-qualified URL for the statement line resource.
amount: Statement line amount will be:
  • Negative for debits
  • Positive for credits
Amount will always be non-zero as zero-amount transactions are ignored.
description: A description of the settlement which, for card purchases, will include the:
  • merchant name
  • card description
  • member name
Example: 
"WALGREENS, Card: Travel, Member: John Smith"
For bank transfers, this field will include the bank account description. Example: 
"Transfer from Acme Checking Account"
Although rare, a settlement may neither represent a purchase nor a bank transfer, and the description may be blank. Example: 
""
card: The card associated with this statement line. May be null if no card was used. Example: 
{
  "id": "90ab2860-768f-4af8-8638-0a0bcdfdbb90",
  "url": "https://api.emburse.com/v1/...",
  "state": "active",
  "description": "Courier #781",
  "last_four": "7781"
}
member: The member responsible for this statement line. May be null if statement line is unassignable. Example: 
{
  "id": "c80e0483-1e03-4387-95b4-b408b10f3e1d",
  "url": "https://api.emburse.com/v1/",
  "email": "john@example.com",
  "first_name": "John",
  "last_name": "Smith"
}
origin: The originating transaction for this statement line. Example: 
{
  "id": "0849b836-bc20-4a83-8218-e50f8c9e56c4",
  "url": "https://api.emburse.com/v1/...",
  "amount": -119.21,
  "state": "completed",
  "category": null,
  "department": null,
  "label": null,
  "location": null,
  "receipt": null,
  "note": "",
  "time": "2016-08-19T04:02:05Z"
}
Multiple statement lines may share the same originating transaction. Although rare, a transaction can be posted using multiple settlements over multiple days.
bank_account: optional If the settlement represents a bank transfer, a bank_account describing the funding source will be provided. Example: 
{
  "description": "Acme Checking Account",
  "name": "ACME INC",
  "number": "8432"
}
Field descriptions:
  • "description" – User-provided description.
  • "name" – Name on account.
  • "number" – Last four digits of account number.
merchant: optional If the settlement represents a purchase, merchant details will be provided. Example: 
{
  "mid": 526559301139368,
  "mcc": 7399,
  "name": "THE UPS STORE 4592",
  "address": "660 4TH ST",
  "city": "SAN FRANCISCO",
  "state": "CA",
  "zip": "94107",
  "country": "US"
}
Field descriptions:
  • "mid" – Merchant ID (Int64).
  • "mcc" – Merchant category code.
  • "name" – Merchant name.
  • "address" – Merchant address.
  • "city" – Address city.
  • "state" – Address state.
  • "zip" – Address zip code.
  • "country" – Address country.
None of these fields are guaranteed to exist. Each field may be set to null.
date: Date that settlement for this statement line was posted. Displayed in the issuer's time zone. Format: yyyy-mm-dd.
time: When the settlement for this statement line was posted (ISO 8601 format).
number: Sequential statement line number.
created_at: When this statement line was created (ISO 8601 format).
Example Statement Line for Card Purchase
{
  "id": "9f1f1183-8ea0-4c43-9152-d68b70f9f2ac",
  "url": "https://api.emburse.com/v1/...",
  "amount": -119.21,
  "description": "WALGREENS, Card: Travel, Member: John Smith",
  "card": {
    "id": "90ab2860-768f-4af8-8638-0a0bcdfdbb90",
    "url": "https://api.emburse.com/v1/...",
    "state": "active",
    "description": "Travel",
    "last_four": "7781"
  },
  "member": {
    "id": "c80e0483-1e03-4387-95b4-b408b10f3e1d",
    "url": "https://api.emburse.com/v1/",
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Smith"
  },
  "merchant": {
    "mid": null,
    "mcc": 5912,
    "name": "WALGREENS",
    "address": "670 4TH ST",
    "city": "SAN FRANCISCO",
    "state": "CA",
    "zip": null,
    "country": "US"
  },
  "origin": {
    "id": "0849b836-bc20-4a83-8218-e50f8c9e56c4",
    "url": "https://api.emburse.com/v1/...",
    "amount": -119.21,
    "state": "completed",
    "category": null,
    "department": null,
    "label": null,
    "location": null,
    "receipt": null,
    "note": "",
    "time": "2016-08-19T04:02:05Z"
  },
  "number": 1005,
  "date": "2016-08-19",
  "time": "2016-08-20T00:05:47Z",
  "created_at": "2016-08-20T00:05:51.474745Z"
}
Example Statement Line for Bank Transfer
{
  "id": "da7b31f3-93dc-45c0-98ed-309c9414a093",
  "url": "https://api.emburse.com/v1/...",
  "amount": 1000.0,
  "description": "Transfer from Acme Checking Account",
  "card": null,
  "member": null,
  "bank_account": {
    "description": "Acme Checking Account",
    "name": "ACME INC",
    "number": "8432"
  },
  "origin": {
    "id": "6577142f-09da-4f23-9a64-7879538d6158",
    "url": "https://api.emburse.com/v1/...",
    "amount": 1000.0,
    "state": "completed",
    "category": null,
    "department": null,
    "label": null,
    "location": null,
    "receipt": null,
    "note": "",
    "time": "2015-09-09T12:09:01Z"
  },
  "number": 476,
  "date": "2015-09-12",
  "time": "2015-09-12T14:57:50Z",
  "created_at": "2015-09-12T14:59:01.492674Z"
}
Example Statement Line for Fee
{
  "id": "62977dbc-ac83-4957-90c7-0823d2382b04",
  "url": "https://api.emburse.com/v1/...",
  "amount": -0.38,
  "description": "FX Fee",
  "card": null,
  "member": null,
  "origin": {
    "id": "62977dbc-ac83-4957-90c7-0823d2382b04",
    "url": "https://api.emburse.com/v1/...",
    "amount": -0.38,
    "state": "completed",
    "category": null,
    "department": null,
    "label": null,
    "location": null,
    "receipt": null,
    "note": "",
    "time": "2015-09-13T04:45:35Z"
  },
  "number": 527,
  "date": "2015-09-12",
  "time": "2015-09-13T04:45:35Z",
  "created_at": "2015-09-13T04:45:52.710562Z"
}

Get Statement

get /v1/accounts/:account_id/statement.format

Retrieve a bank statement for a specific account in a specific format. The statement format is added to the end of the URL and may be one of the following values: csv, ofx, or pdf. In addition, the following GET parameters are supported:

GET Param Description
start_date: default: 1st of month Settlements posted on or after this date will be included within the exported statement. Uses your issuer's time zone. Format: yyyy-mm-dd.
end_date: default: today Settlements posted on or before this date will be included within the exported statement. Uses your issuer's time zone. Format: yyyy-mm-dd. start_date and end_date may be no more than 180 days apart.
Example Request
curl -O -H "Authorization: Token ACCESS_TOKEN" "https://api.emburse.com/v1/accounts/ACCOUNT_ID/statement.ofx?start_date=2016-08-01&end_date=2016-08-31"

List Statement Lines

get /v1/accounts/:account_id/statement-lines

Retrieve a list of statement lines for a specific account. By default, statement lines are sorted with the ordering GET parameter set to -number so that statement lines are returned in reverse chronological order based on when transaction settlements were posted.

Ordering Description
number Results will be sorted in chronological order based on transaction settlement times. If using -number, results will be sorted in reverse chronological order.

In addition, statement lines may be filtered by date and number:

GET Param Description
start_date: Settlements posted on or after this date will be returned. Uses your issuer's time zone. Format: yyyy-mm-dd.
end_date: Settlements posted on or before this date will be returned. Uses your issuer's time zone. Format: yyyy-mm-dd.
number: The statement line with a matching line number will be returned.
number__gt: Only statement lines with numbers greater than this value will be returned.
number__lt: Only statement lines with numbers less than this value will be returned.
Example Request
curl -H "Authorization: Token ACCESS_TOKEN" "https://api.emburse.com/v1/accounts/ACCOUNT_ID/statement-lines?ordering=number&start_date=2016-08-01"

Get Statement Line

get /v1/accounts/:account_id/statement-lines/:statement_line_id

Retrieve a statement line by ID. Both an account ID and a statement_line ID are required.

Example Request
curl -H "Authorization: Token ACCESS_TOKEN" "https://api.emburse.com/v1/accounts/ACCOUNT_ID/statement-lines/STATEMENT_LINE_ID"

Categories

A category may be assigned to cards and transactions. When a category is assigned to a card, that category will be set on any transactions created using the card.

Category Object

Field Description
id: Category UUID.
url: A fully-qualified URL for the category resource.
name: Category name.
code: A category code used for accounting. May be a unique numeric string or null.
parent: Parent for this category (as an object). The parent field is recursive.
created_at: When this category was created (ISO 8601 format).
Example Category Object
{
  "id": "ce0693b7-53dd-47cf-b145-dfaa6c9f7c00",
  "url": "https://api.emburse.com/v1/...",
  "code": "1002",
  "name": "Office Expenses",
  "parent": {
      "id": "b93e384f-204e-4582-b97d-2243bf7abac1",
      "url": "https://api.emburse.com/v1/...",
      "code": "1000",
      "name": "Expenses",
      "parent": null
  },
  "created_at": "2016-02-28T08:40:53.373895Z"
}

List Categories

get /v1/categories

Retrieve a list of categories.

Example Request
curl -H "Authorization: Token ACCESS_TOKEN" "https://api.emburse.com/v1/categories"

Get Category

get /v1/categories/:category_id

Retrieve a category by ID.

Example Request
curl -H "Authorization: Token ACCESS_TOKEN" "https://api.emburse.com/v1/categories/ce0693b7-53dd-47cf-b145-dfaa6c9f7c00"

Create Category

post /v1/categories

Create a new category. Each code must be a unique numeric string or null.

Example Request
curl "https://api.emburse.com/v1/categories" -H "Authorization: Token ACCESS_TOKEN" -H "Content-Type: application/json" -X POST -d '{"name": "Transportation", "code": null}'

Update Category

put /v1/categories/:category_id

Update an existing category.

Example Request
curl "https://api.emburse.com/v1/categories/CATEGORY_ID" -H "Authorization: Token ACCESS_TOKEN" -H "Content-Type: application/json" -X PUT -d '{"code": 1003}'

Delete Category

delete /v1/categories/:category_id

Delete an existing category. Deleted category objects are removed from cards and transactions.

Example Request
curl "https://api.emburse.com/v1/categories/CATEGORY_ID" -H "Authorization: Token ACCESS_TOKEN" -H "Content-Type: application/json" -X DELETE

Departments

A department may be assigned to cards and transactions. When a department is assigned to a card, that department will be set on any transactions created using the card.

Department Object

Field Description
id: Department UUID.
url: A fully-qualified URL for the department resource.
name: Department name.
code: A department code used for accounting. May be a unique numeric string or null.
parent: Parent for this department (as an object). The parent field is recursive.
created_at: When this department was created (ISO 8601 format).
Example Department Object
{
  "id": "5f93e176-7064-46dd-b517-cf1a8454d0f1",
  "url": "https://api.emburse.com/v1/...",
  "name": "Finance",
  "parent": {
      "id": "b93e384f-204e-4582-b97d-2243bf7abac1",
      "url": "https://api.emburse.com/v1/...",
      "name": "Money",
      "code": "1000",
      "parent": null
  },
  "created_at": "2016-03-11T11:59:27.666749Z"
}

List Departments

get /v1/departments

Retrieve a list of departments.

Example Request
curl -H "Authorization: Token ACCESS_TOKEN" "https://api.emburse.com/v1/departments"

Get Department

get /v1/departments/:department_id

Retrieve a department by ID.

Example Request
curl -H "Authorization: Token ACCESS_TOKEN" "https://api.emburse.com/v1/departments/5f93e176-7064-46dd-b517-cf1a8454d0f1"

Create Department

post /v1/departments

Create a new department. Each code must be a unique numeric string or null.

Example Request
curl "https://api.emburse.com/v1/departments" -H "Authorization: Token ACCESS_TOKEN" -H "Content-Type: application/json" -X POST -d '{"name": "Engineering", "code": null}'

Update Department

put /v1/departments/:department_id

Update an existing department.

Example Request
curl "https://api.emburse.com/v1/departments/DEPARTMENT_ID" -H "Authorization: Token ACCESS_TOKEN" -H "Content-Type: application/json" -X PUT -d '{"name": "Sales & Marketing"}'

Delete Department

delete /v1/departments/:department_id

Delete an existing department. Deleted department objects are removed from cards and transactions.

Example Request
curl "https://api.emburse.com/v1/departments/DEPARTMENT_ID" -H "Authorization: Token ACCESS_TOKEN" -H "Content-Type: application/json" -X DELETE

Labels

A label may be assigned to cards and transactions. When a label is assigned to a card, that label will be set on any transactions created using the card.

Label Object

Field Description
id: Label UUID.
url: A fully-qualified URL for the label resource.
name: Label name.
code: A label code used for accounting. May be a unique numeric string or null.
parent: Parent for this label (as an object). The parent field is recursive.
created_at: When this label was created (ISO 8601 format).
Example Label Object
{
  "id": "066a22d6-943c-4a45-b2ec-9ccd417e2685",
  "url": "https://api.emburse.com/v1/...",
  "name": "Los Angeles",
  "parent": {
      "id": "b93e384f-204e-4582-b97d-2243bf7abac1",
      "url": "https://api.emburse.com/v1/labels/...",
      "name": "California",
      "code": "1000",
      "parent": null
  },
  "created_at": "2016-03-11T11:57:35.467667Z"
}

List Labels

get /v1/labels

Retrieve a list of labels.

Example Request
curl -H "Authorization: Token ACCESS_TOKEN" "https://api.emburse.com/v1/labels"

Get Label

get /v1/labels/:label_id

Retrieve a label by ID.

Example Request
curl -H "Authorization: Token ACCESS_TOKEN" "https://api.emburse.com/v1/labels/066a22d6-943c-4a45-b2ec-9ccd417e2685"

Create Label

post /v1/labels

Create a new label. Each code must be a unique numeric string or null.

Example Request
curl "https://api.emburse.com/v1/labels" -H "Authorization: Token ACCESS_TOKEN" -H "Content-Type: application/json" -X POST -d '{"name": "Chicago", "code": null}'

Update Label

put /v1/labels/:label_id

Update an existing label.

Example Request
curl "https://api.emburse.com/v1/labels/LABEL_ID" -H "Authorization: Token ACCESS_TOKEN" -H "Content-Type: application/json" -X PUT -d '{"name": "Los Angeles"}'

Delete Label

delete /v1/labels/:label_id

Delete an existing label. Deleted label objects are removed from cards and transactions.

Example Request
curl "https://api.emburse.com/v1/labels/LABEL_ID" -H "Authorization: Token ACCESS_TOKEN" -H "Content-Type: application/json" -X DELETE

Locations

A location may be assigned to cards and transactions. When a location is assigned to a card, that location will be set on any transactions created using the card.

Location Object

Field Description
id: Location UUID.
url: A fully-qualified URL for the location resource.
name: Location name.
code: A location code used for accounting. May be a unique numeric string or null.
parent: Parent for this location (as an object). The parent field is recursive.
created_at: When this location was created (ISO 8601 format).
Example Location Object
{
  "id": "066a22d6-943c-4a45-b2ec-9ccd417e2685",
  "url": "https://api.emburse.com/v1/...",
  "name": "Los Angeles",
  "parent": {
      "id": "b93e384f-204e-4582-b97d-2243bf7abac1",
      "url": "https://api.emburse.com/v1/...",
      "name": "California",
      "code": "1000"
      "parent": null
  },
  "created_at": "2016-03-11T11:57:35.467667Z"
}

List Locations

get /v1/locations

Retrieve a list of locations.

Example Request
curl -H "Authorization: Token ACCESS_TOKEN" "https://api.emburse.com/v1/locations"

Get Location

get /v1/locations/:location_id

Retrieve a location by ID.

Example Request
curl -H "Authorization: Token ACCESS_TOKEN" "https://api.emburse.com/v1/locations/066a22d6-943c-4a45-b2ec-9ccd417e2685"

Create Location

post /v1/locations

Create a new location. Each code must be a unique numeric string or null.

Example Request
curl "https://api.emburse.com/v1/locations" -H "Authorization: Token ACCESS_TOKEN" -H "Content-Type: application/json" -X POST -d '{"name": "Chicago", "code": null}'

Update Location

put /v1/locations/:location_id

Update an existing location.

Example Request
curl "https://api.emburse.com/v1/locations/LOCATION_ID" -H "Authorization: Token ACCESS_TOKEN" -H "Content-Type: application/json" -X PUT -d '{"name": "Los Angeles"}'

Delete Location

delete /v1/locations/:location_id

Delete an existing location. Deleted location objects are removed from cards and transactions.

Example Request
curl "https://api.emburse.com/v1/locations/LOCATION_ID" -H "Authorization: Token ACCESS_TOKEN" -H "Content-Type: application/json" -X DELETE

Webhooks

Emburse's API can push real-time notifications to your app. To receive webhook notifications, add one or more webhook URLs when registering your web application.

Webhook endpoints should expect a POST request each time one or more Emburse events have been triggered. The request body will contain a JSON array of event objects.

Event Types

Type Description
transaction.created Triggered each time a new transaction object is created.
transaction.updated Triggered each time an existing transaction object is updated.
Example Webhook Payload
[
  {
    "event": "transaction.created",
    "transaction": {
      "id": "9706a780-5333-43a4-a666-a69db74e993f"
    },
    "company": {
      "id": "cb93de0c-dfdf-4c7a-bc88-ef48548ea1d5"
    }
  }
]

Transaction Events

The "transaction.created" event is triggered each time a new transaction is created, and the "transaction.updated" event is triggered each time an existing transaction is updated. A transaction event will have the following fields:

Field Description
event: "transaction.created" or "transaction.updated".
transaction: Object with transaction ID. Example: 
{
  "id": "9706a780-5333-43a4-a666-a69db74e993f"
}
company: Object with company ID. Example: 
{
  "id": "cb93de0c-dfdf-4c7a-bc88-ef48548ea1d5"
}

Transaction details must be retrieved using a subsequent request to the transactions API endpoint. The company ID is provided to assist with the selection of an access_token if multiple tokens are being used.

Example Transaction Event
{
  "event": "transaction.updated",
  "transaction": {
    "id": "9706a780-5333-43a4-a666-a69db74e993f"
  },
  "company": {
    "id": "cb93de0c-dfdf-4c7a-bc88-ef48548ea1d5"
  }
}
See it for yourself ✕

Try our fully functioning demo account and see if Emburse is the right fit for you.

Try it now