Back to API Docs

Durable Data API v1.0

Emburse is a member of the Financial Data Exchange and implements the Durable Data API (DDA) to facilitate integrations with bank data aggregators and expense management platforms.

Authorization

Per the DDA specification, authorization is implemented using the OAuth2 protocol. We support the FinancialInformation scope when requesting access tokens for granting read-only access to client information. Emburse's OAuth implementation supports both web authorizations via browser redirects and authorizations through direct submission of password credentials.

Once an access token is granted, each request to Emburse's DDA endpoints must contain an access token within its Authorization header. A Bearer type access token is required:

Authorization: Bearer ACCESS_TOKEN

View full OAuth documentation.

Request Integration

Please contact support@emburse.com for permission to access our DDA services and for permission to use the FinancialInformation scope when requesting OAuth2 access tokens.

Endpoints

The Durable Data API supports the sharing of information derived from a broad range of financial institutions. Emburse's implementation focuses upon providing statement information as a credit card provider to bank data aggregators.

Emburse implements the DDA 1.0 interface and supports the DDA endpoints listed below. Emburse's base URL for all DDA requests is:

https://api.emburse.com/dda/v1/

HTTP Headers

The Emburse DDA server interaction is accompanied with exchange of some HTTP Headers.

Content Negotiation

Durable Data API clients and servers use standard HTTP headers to negotiate transport options. At the current time the valid option is application/json, passing unsupported content type will cause server to return 406 status code.

Accept: application/json

The Durable Data API server uses the Content-Type response header to inform the client of the response syntax.

Content-Type: application/json

Date

The Durable Data API server returns a Date header with every response.

Date: Tue, 11 Sep 2012 19:43:31 GMT

Interaction Tracking

The Durable Data API client may send the DDA-InteractionId request header to the server to help correlate log entries between client and server. Example:

DDA-InteractionId: c770aef3-6784-41f7-8e0e-ff5f97bddb3a

The Durable Data API server will also send DDAInteractionId as a response header with value equal to the value sent by the client, or a unique value generated by the server if the client did not send DDA-InteractionId.

Account

post /dda/v1/account

Retrieve an account.

Request Parameters

The following parameters should be specified as form data in the request body:

Param Description
accountId: Emburse account identifier.
Example Request [POST]
curl "https://api.emburse.com/dda/v1/account" -X POST -H "Authorization: Bearer ACCESS_TOKEN"  -H "Content-Type: application/x-www-form-urlencoded" -d "accountID=066a22d6..."
Example Response
200 OK
{
    "DepositAccount": {
        "AccountId": "066a22d6...",
        "AccountType": "CHECKING",
        "DisplayName": "Acme, Inc.",
        "Status": "OPEN",
        "Nickname": "Emburse account for Acme, Inc.",
        "Currency": {
            "CurrencyCode": "USD"
        },
        "AccountNumber": "123451234567",
        "BalanceType": "ASSET",
        "InterestRate": 0,
        "TransferIn": false,
        "TransferOut": false,
        "LastActivityDate": "2018-12-21T12:43:15Z",
        "TransactionsIncluded": false,
        "BalanceAsOf": "2018-12-21T12:43:15Z",
        "CurrentBalance": 123.45,
        "AvailableBalance": 123.45
    }
}

Account List

get /dda/v1/accountlist

Get a lightweight list of accounts for the current token.

Example Request [GET]
curl "https://api.emburse.com/dda/v1/accountlist" -H "Authorization: Bearer ACCESS_TOKEN"
Example Response
200 OK
{
    "AccountDescriptorList": [
        {
            "AccountId": "066a22d6...",
            "AccountType": "CHECKING",
            "DisplayName": "Acme, Inc.",
            "Status": "OPEN",
        }
    ]
}

Accounts

get /dda/v1/accountsdetails

Retrieve all account information (details & transactions) for the current token.

Example Request [GET]
curl "https://api.emburse.com/dda/v1/accountsdetails" -H "Authorization: Bearer ACCESS_TOKEN"
Example Response
200 OK
{
    "Accounts": [
        {
            "AccountId": "066a22d6...",
            "AccountType": "CHECKING",
            "DisplayName": "Acme, Inc.",
            "Status": "OPEN",
            "Nickname": "Emburse account for Acme, Inc.",
            "Currency": {
                "CurrencyCode": "USD"
            },
            "AccountNumber": "123451234567",
            "BalanceType": "ASSET",
            "InterestRate": 0,
            "TransferIn": false,
            "TransferOut": false,
            "LastActivityDate": "2018-12-21T12:43:15Z",
            "TransactionsIncluded": false,
            "BalanceAsOf": "2018-12-21T12:43:15Z",
            "CurrentBalance": 123.45,
            "AvailableBalance": 123.45
        },
    ]
}

Get statements

post /dda/v1/account/statements

Get a list of account statements.

Request Parameters

The following parameters should be specified as form data in the request body:

Param Description
accountId: Emburse account identifier.
startTime: optional Start time for use in retrieval; ISO 8601 date including zone indicator or combined date time including zone indicator.
endTime: optional End time for use in retrieval; ISO 8601 date including zone indicator or combined date time including zone indicator.
Example Request [POST]
curl "https://api.emburse.com/dda/v1/account/statements" -H "Authorization: Bearer ACCESS_TOKEN"
    -d 'accountId=066a22d6...&startTime=2018-08-30Z&endTime=2018-09-11Z
Example Response

{
    "Statements": [
        {
            "AccountId": "066a22d6...",
            "StatementId": "2018-08-30",
            "StatementDate": "2018-08-30"
        },
        {
            "AccountId": "066a22d6...",
            "StatementId": "2018-09-03",
            "StatementDate": "2018-09-03"
        }
    ]
}

    

Statement

post /dda/v1/account/statement

Get an account statement.

Request Parameters

The following parameters should be specified as form data in the request body:

Param Description
accountId: Emburse account identifier.
statementId: Statement identifier (ISO 8601 Date)
Example Request [POST]
curl "https://api.emburse.com/dda/v1/account/statement" -H "Authorization: Bearer ACCESS_TOKEN"
    -d 'accountId=066a22d6...&statementId=2018-08-30'
Example Response

HTTP/1.1 200 OK
Content-Type: application/pdf

<Binary Data>

    

Customer

get /dda/v1/customer

Get information about the customer within the authorization scope.

Example Request [GET]
curl "https://api.emburse.com/dda/v1/customer" -H "Authorization: Bearer ACCESS_TOKEN"
Example Response
200 OK
{
    "Customer": {
        "CustomerId": "7646cbfb...",
        "Name": {
            "First": "John",
            "Last": "Doe",
            "Company": "Acme, Inc."
        },
        "Email": [
            "owner@acme.example.com"
        ],
        "Addresses": [
            {
                "Type": "BUSINESS",
                "Line1": "123 Sesame Street",
                "Line2": "",
                "Line3": "",
                "City": "New York City",
                "State": "NY",
                "Zip": "10000",
                "Country": "US"
            }
        ],
        "Telephones": [
            "+1234567890"
        ]
    }
}

Transactions

post /dda/v1/account/transactions

Retrieve account transactions.

Request Parameters

The following parameters should be specified as form data in the request body:

Param Description
accountId: Emburse account identifier.
startTime: optional Start time for use in retrieval; ISO 8601 date including zone indicator or combined date time including zone indicator.
endTime: optional End time for use in retrieval; ISO 8601 date including zone indicator or combined date time including zone indicator.
page: optional Page number of the paginated transactions list.
Example Request [POST]
curl "https://api.emburse.com/dda/v1/account/transactions"
-X POST
-H "Authorization: Bearer ACCESS_TOKEN"
-H "Content-Type: application/x-www-form-urlencoded"
-d "accountId=066a22d6...&startTime=2018-12-01Z&endTime=2018-12-31Z&page=1"
Example Response
200 OK
{
    "Total": 1201,
    "TotalPages": 13,
    "Page": 1,
    "Transactions": [
        {
            "AccountId": "066a22d6...",
            "TransactionId": "9d579486...",
            "ReferenceTransactionId": "b5e8c82f...",
            "PostedTimestamp": "2018-12-03T19:54:16Z",
            "TransactionTimestamp": "2018-12-03T19:54:16Z",
            "Description": "Personal Expense at Corporation Inc.",
            "Memo": "",
            "DebitCreditMemo": "DEBIT",
            "Category": "5111",
            "Status": "POSTED",
            "Amount": 100,
        },
        ...
    ]
}

Capability

get /dda/v1/capability

Get information about this API’s capabilities.

Example Request [GET]
curl "https://api.emburse.com/dda/v1/capability" -H "Authorization: Bearer ACCESS_TOKEN"
Example Response
200 OK
{
    "Capability": {
        "AllowedConnections": 10,
        "SupportsCustomer": true,
        "SupportsAccounts": true,
        "SupportsTransactions": true,
        "SupportsStatements": true,
        "SupportsImage": false,
        "SupportsBillPay": false,
        "SupportsTransfer": false,
        "MessageFormat": "JSON"
    }
}

Availability

get /dda/v1/availability

Get information about this API’s availability.

Example Request [GET]
curl "https://api.emburse.com/dda/v1/availability" -H "Authorization: Bearer ACCESS_TOKEN"
Example Response
200 OK
{
    "Availability": {
        "CurrentStatus": "OK",
        "CurrentStatusDesc": "OK"
    }
}
See it for yourself

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