API basics

Requests

Base URL

All API access are over HTTPS, and accessed from the api.bridgeapi.io/v2 domain.
Any non-secure requests are met with a redirect (HTTP 301) to the HTTPS equivalent URI.

HTTP verbs

As per RESTful design patterns, the Bridge API implements following HTTP verbs:

• GET - Read resources
• POST - Create new resources
• PUT - Modify existing resources
• DELETE - Remove resources

Parameters

Many API methods take parameters.
For GET requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameter:

curl "https://api.bridgeapi.io/v2/users/f3cce1aa-be0d-11e5-af4e-104c2aec0665/transactions?limit=100&after=123456789" \
    -H 'Bridge-Version: VERSION'

In this example, the f3cce1aa-be0d-11e5-af4e-104c2aec0665 value is provided for the :uuid parameter in the path while :limit and :after are passed in the query string.

For POST, PUT, and DELETE requests, parameters not included in the URL should be encoded as JSON with a Content-Type header of application/json:

curl "https://api.bridgeapi.io/v2/items" \
    -X GET \
    -H 'Bridge-Version: VERSION' \
    -H 'Client-Id: MY_CLIENT_ID' \
    -H 'Client-Secret: MY_CLIENT_SECRET' \
    -H 'Authorization: Bearer TOP_SECRET_ACCESS_TOKEN'

HTTP status codes

All responses use standard HTTP status codes.

Usually, codes in the 2xx range indicate success, codes in the 4xx range are for client-related failures, and 5xx codes are for Bridge-related issues (these are rare).

• 200 OK Successful request.
• 201 Created New resource created.
• 202 Accepted The request has been accepted for processing, but the processing has not been completed.
• 204 No Content Resource deleted.
• 400 Bad Request The request is malformed. Check the parameters or the syntax.
• 401 Unauthorized Couldn’t authenticate the request.
• 403 Forbidden The request is not allowed.
• 404 Not Found No such resource.
• 409 Conflict The resource already exists.
• 415 Unsupported media type The resource requires Content-Type: application/json header and a JSON body.
• 422 Unprocessable entity The provided JSON is not valid.
• 429 Too Many Requests Too many requests hit the API too quickly. See Rate limits.
• 500 Internal Server Error Something went wrong on our end (these are rare).

Errors

{
    "type": "conflict",
    "message": "User '[email protected]' already exists",
    "documentation_url": null
}

Rate limits

Bridge API rate limits calls with the following pattern:

• 2000 requests per Application per period of 5 minutes

• 60 requests per User per period of 60 seconds

• 10 /authenticate requests per User per period of 60 seconds

• Other undisclosed limits apply to endpoints that do not require authentication

📘

Raising the rate limit

The rate limit of 2000 requests / 5 minutes can be raised for large Applications. Please contact our support if you are in this situation.

Timestamps and dates

All timestamps are returned in ISO 8601 format with time in including milliseconds : yyyy-MM-ddTHH:mm:ss.SSSZ
All dates are returned in format: yyyy-MM-dd

🚧

List updated transactions needs a timestamp parameter whereas List transactions needs a date parameter.

Pagination

All endpoints which return an object list, support pagination with pagination information inside a pagination object.

You can for instance list users, list banks or list transactions.

Bridge uses a cursor based pagination via the after parameter.

❗️

Do not forge, nor store the after cursors as they may change overtime.

📘

By default, all objects are ordered and paginated reverse chronologically with a limit of 50.

Options

Response

Paginated results are always returned in an array and include the following information in the pagination object:

curl "https://api.bridgeapi.io/transactions?limit=2" \
    -X GET \
    -H 'Bridge-Version: VERSION' \
    -H 'Client-Id: MY_CLIENT_ID' \
    -H 'Client-Secret: MY_CLIENT_SECRET' \
    -H 'Authorization: Bearer TOP_SECRET_ACCESS_TOKEN'

{  
    "resources": [
        {
            "id": 9,
            //...
        },
        {
            "id": 8,
            //...
        }
    ],
    "pagination": {
        "next_uri": "/v2/transactions?limit=2&after=MzIx"
    }
}

Versioning

When we make backwards incompatible changes to the API, we release a new version with a new date.

The following changes are considered backwards compatible:

• Adding new API endpoints
• Adding new properties to the responses from existing API endpoints
• Adding optional request parameters to existing API endpoints
• Altering the message attributes returned by validation failures / other errors