API Design

The Atlar API is a resource-based JSON API, following RESTful standards.

What is considered a Non-Breaking change

Endpoints, fields, and request parameters will not be removed or changed without a version change.
However, non-breaking changes to the API may be introduced without a version change.
This includes new fields to JSON objects and new parameters to requests.
In practice, this means that your clients need to handle unknown/unmapped fields and parameters.
Introduction of new fields/parameters will not impact behavior of existing fields/parameters.

Structure

The Atlar API is resource-oriented and follows REST/CRUD practices.

Namespaces

Atlar API endpoints are grouped into product namespaces:

• financial-data — Your bank accounts, account transactions, account balances etc.
• payments — Credit transfers, direct debits, counterparties etc.

📘

No trailing slashes, and all paths have pluralized resource names

Authentication

The Atlar API supports both OAuth 2.0 access tokens and HTTP Basic authentication.
It is recommended to use the OAuth 2.0 access token flow.

OAuth 2.0 Access Token

The Atlar API supports OAuth 2.0 access tokens using the client credentials grant type.
Use the access token endpoint to acquire an access token.
Use the ACCESS_KEY and SECRET that you retrieve when creating programmatic access users as OAuth 2.0 client credentials (ACCESS_KEY as client_id and SECRET as client_secret).

Example

Step 1. Acquire an access token

curl -s -d 'grant_type=client_credentials' -u '<ACCESS_KEY>:<SECRET>' https://api.atlar.com/iam/v2beta/oauth2/token

This will return an OAuth 2.0 access token response in the form:

{"access_token":"<ACCESS_TOKEN>","token_type":"Bearer","expires_in":300}

ℹ️

The access token will have a limited lifetime given by the property "expires_in" (time-to-live in seconds).

Step 2. Use the access token as a Bearer token

Use the ACCESS_TOKEN value from the token response as Bearer token authentication, i.e. pass the HTTP header Authorization: Bearer <ACCESS_TOKEN>.

For example, listing Accounts using curl:

curl 'https://api.atlar.com/financial-data/v2/accounts' --oauth2-bearer '<ACCESS_TOKEN>'

HTTP Basic Authentication

Use HTTP Basic auth with the ACCESS_KEY and SECRET that you retrieve when creating programmatic access users.

Listing Accounts using curl:

curl 'https://api.atlar.com/financial-data/v2/accounts' -u '<ACCESS_KEY>:<SECRET>'

Pagination

Pagination works the same on all List endpoints.
This includes GET endpoints for resource collections, e.g. GET /financial-data/v2/transactions or GET /payments/v2/credit-transfers.

The request has two common query parameters that can be used: limit and token.

• limit: must be between 1 and 500. Values outside this range will be coerced to the nearest limit. Defaults to 100 if not provided.
• token: specifies the starting point for pagination.

Examples:

• GET /financial-data/v2/transactions?limit=20 will give 20 transactions (or up to 20 if fewer exist).
• GET /financial-data/v2/transactions?limit=20&token={TOKEN} will give 20 transactions, starting from {TOKEN}.

The list response object will have the same shape across resources, containing four fields:

• items – An array containing the resource items. Required but may be empty.
• nextToken – Token to use to continue pagination. Empty if no more items exist.
• token – The token used for the request. Empty if no token was specified.
• limit – The effective limit used to process the request.

❗️

Never use the length of the items list compared to the limit to determine whether more pages exist.
Items returned may be fewer than the limit even if more items remain.

📘

Keep filter query parameters consistent while paginating.
If query parameters change, always restart pagination by omitting the token value.

Example Response:

{
  "nextToken": "The token that should be used to get the next page, empty if no more",
  "token": "The token used for this query",
  "limit": 20,
  "items": []
}

Errors

The Atlar API uses the following standard error codes:

Request IDs

Each API request is assigned a unique request identifier.
This identifier is included in the HTTP header request-id.
Provide this identifier when contacting support about a specific request.

Idempotency

The Atlar API supports idempotency to safely retry requests without performing the same operation multiple times.
This is especially useful if a request is disrupted and the client does not know whether the server performed the operation.

To make a request idempotent, supply the optional HTTP header Idempotency-Key.
The key is ignored for GET and DELETE requests and expires automatically 24 hours after first use.
Uniqueness is bound to the organization and endpoint (method and path).

If a second request with the same key is received before the first is complete, the server responds with 425 Too Early, which is safe to retry.

A test endpoint exists for experimenting with idempotency:

POST /v1/idempotency-test

Optional query parameters:

• status: Specifies the response status code.
• sleep: Server sleep duration in milliseconds before responding.

Safe Updates using If-Match and ETag

Many Atlar API resources support updates (primarily via PATCH).
To prevent conflicting updates and avoid the lost update problem, specify the resource’s etag value in the If-Match HTTP header.

Example JSON response:

{
  "id": "a2072298-4c27-40d6-a4ff-050006e63415",
  "etag": "version:3",
  ...
}

Subsequent PATCH request header:

If-Match: version:3

Note: The etag value is a plain string and should not be quoted in the HTTP header.

External IDs

Many API resources can be identified by an external ID you provide.
Specify the externalId property when creating the resource.
The resource can then be accessed using:

GET /{namespace}/{version}/resource/external:{externalId}

Values for externalId must match the regex:

^[a-zA-Z0-9._\-+=]{1,64}$

Refer to the API Reference for details on which resources support this.