API basics

Requests

Base URL

All API access is conducted over HTTPS and is accessible from the api.bridgeapi.io/v2 domain.
Any non-secure requests will automatically redirect (HTTP 301) to the equivalent HTTPS URI.

HTTP verbs

Bridge API follows RESTful design patterns. Our API implements following HTTP verbs:

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

Parameters

Many API methods accept parameters.
For GETrequests, any parameters not specified as a segment in the path should be passed as HTTP query string parameters:

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 follow standard HTTP status codes.
Typically, codes in the 2xx range signify success, codes in the 4xx range are for client-related issues, and 5xx codes are reserved for Bridge-related problems (which 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
string
Machine readable error message.
message
string
Human readable error message.
documentation_url
string, optional
Optional link to documentation.
{
	"type": "conflict",
	"message": "User '[email protected]' already exists",
	"documentation_url": null
}

Rate limits

Bridge API enforces rate limits with the following pattern:

  • 2000 requests per Application within a 5-minute period

  • 60 requests per User within a 60-second period

  • 10 /authenticate requests per User within a 60-second period

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

📘

Raising the rate limit

For large applications, the rate limit of 2000 requests per 5 minutes can be increased. Please contact our support team if you require this adjustment.

Timestamps and dates

All timestamps are provided in ISO 8601 format with millisecond precision : yyyy-MM-ddTHH:mm:ss.SSSZ
Dates are returned in the format: yyyy-MM-dd

🚧

List updated transactions endpoint requires a timestamp parameter, while the List transactions endpoint requires a date parameter.

Pagination

All endpoints that return a list of objects support pagination, with pagination information available within 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 or store the after cursors, as they may change over time.

📘

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

Options

limit
integer
Number of results per call. Accepted values: 1 - 500.
Default 50.
after
string
Cursor pointing to the start of the desired set.

Response

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

next_uriTo make it easier, the API will build the next call into next_uri together with all the current pagination parameters.
Can be null if there are no more results in the list.
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

We release a new version of the API with a new date when making backward-incompatible changes. The following changes are considered backward-compatible:

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