Basics

Requests

Base URL

All API access are over HTTPS, and accessed from the sync.bankin.com/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://sync.bankin.com/v2/users/f3cce1aa-be0d-11e5-af4e-104c2aec0665/transactions?limit=100&before=123456789" \
	-H 'Bankin-Version: VERSION'

In this example, the f3cce1aa-be0d-11e5-af4e-104c2aec0665 value is provided for the :uuid parameter in the path while :limit and :before 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://sync.bankin.com/v2/items" \
	-X GET \
  -H 'Bankin-Version: VERSION' \
	-H 'Client-Id: MY_CLIENT_ID' \
	-H 'Client-Secret: MY_CLIENT_SECRET' \
	-H 'Authorization: Bearer TOP_SECRET_ACCESS_TOKEN'

Fields

Referencing other objects

All resources have a resource_type field which explicitly represents its type and a resource_uri field for its location.

All resources have a full representation with all its fields and a mini representation containing only its id, resource_type, resource_uri.
The mini representation is used when linking resources to other resources.

These are meant to provide explicit URIs so that proper API clients don't need to build URIs on their own. It is highly recommended that API clients use these. Doing so will make future upgrades of the API easier for developers.

The example below shows the transation resource full representation and its linked account using the mini representation:

{
	id: 120,
	amount: 300,
	// ...
	account: {
		id: 87,
		resource_type: "account",
		resource_uri: "/v2/accounts/87"
	},
	resource_type: "transaction",
	resource_uri: "/v2/transactions/120"
}

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 transactions needs a timestamp parameter whereas List updated 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.

Bankin' uses a cursor based pagination via the after and before parameters.
If both parameters are provided, only before is used.

❗️
Do not forge, nor store the before and after cursors as they may change overtime.

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

Options


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

Response

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


`previous_uri`	To make it easier, the API will build the previous call into `previous_uri` together with all the current pagination parameters. Can be `null` if the returned page is the first one.
`next_uri`	To 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://sync.bankin.com/v2/transactions?limit=2" \
	-X GET \
  -H 'Bankin-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": {
		"previous_uri": null,
		"next_uri": "/v2/transactions?limit=2&after=MzIx",
	}
}