API reference

Integration simplicity first — Our API features JSON requests and responses, standard HTTP response codes, authentication, and expressive URL's.

About the API

All requests are authenticated using a credential pair, a public key and a secret.
To help you distinguish between them, the public key is prefixed with “public-key-” and the secret is prefixed with “secret-”.
The prefixes are part of the public key and secret respectively and should be intact when used.
To generate new credentials or manage existing ones, sign in to your account and go to the settings tab.
Remember to keep your secret safe and never store it in ly accessible areas such as in git repositories, client code or in apps.

Authentication to the API is performed via HTTP Basic Auth.
Provide your public key as the basic auth username value and your secret as the password value.
curl -u PUBLIC_KEY:SECRET Most http clients have built-in support for basic auth in which case you only have to provide the credentials (like in the example above). If you have to construct the basic auth header manually, the formula is base64(public key + : + secret).
# python example from base64 import standard_b64encode headers.append({ 'Authorization': 'Basic %s' % standard_b64encode( b'PUBLIC_KEY' + b':' + b'SECRET' ).decode() }) API requests without authentication will fail.
All API requests must be POST requests made over HTTPS.

The request body must be a JSON-encoded string containing the request properties.
If no properties are required, the request body can be omitted completely.
For integration simplicity, the encoding of any valid JSON object, including empty ones, is always guaranteed to be accepted.
Extraneous properties are automatically omitted.

All request properties have a required type, such as string, integer, or boolean.
Make sure to use the correct types when constructing requests, and consult the API reference if needed.
The API will return an error if the wrong type is used, and the error message will point to the correct type or format.

All requests return a response in the form of a JSON-encoded string containing the response data.
If the response is empty, an empty JSON object is returned.
As such, the response is always safe to JSON-decode.
The API uses conventional HTTP response codes to indicate the success or failure of an API request.
Codes in the 2xx range indicate success.
Codes in the 4xx range indicate an error due to the request itself (e.g., a required property was omitted, or an invalid property value was provided).
Codes in the 5xx range indicate an internal error.
Some errors include a message that briefly explains the error and how to resolve it.
# error example { "error_message": "No session found with id: 123", "error_name": "SessionNotFound" } Possible codes are:
• 200 OK: Everything worked as expected.
• 400 Bad Request: The request was rejected, usually because a required property is missing in the request.
• 401 Unauthorized: No valid API credentials were provided in the request.
• 403 Forbidden: The request was forbidden, usually because of lack of permissions.
• 404 Not Found: The requested resource was not found.
• 500 Internal Server Error: The request was accepted, but something went wrong on our end (should be rare).

We recommend retrying failed requests, except for errors in the 4xx range.
On failure, retry up to 4 times using an exponential backoff algorithm (e.g. retry after 2, 4, 8 and finally after 16 seconds).

The timeout for a given request is 60 seconds.
To keep the API simple to understand and integrate, we re-use the same design principles and common patterns throughout.
The URL structure is always:
http://localhost:4000/api/[class].[method] For example http://localhost:4000/api/session.create

All methods that operate on the same class (or object) are bundled together.
Most classes have the same common methods, such as:

• create for creating a new object
• get for retrieving an object by id
• list for retrieving a filtered list of objects
• update for updating an existing object by id
• delete for deleting an object by id

A method is always returning an object or a list of objects of the class that is being requested.
Responses are always flat and do not contain nested objects.
Property names, such as id, always refer to the same class.
If referring to another class, the property name is prefixed with that class.
# a transaction object retrieved with /api/transaction.get { "id": 123 # refers to the same class, i.e. the transaction id } # a bill object retrieved with /api/bill.get { "id": 456 # refers to the same class, i.e. the bill id "transaction_id": 123 # refers to the transaction id } Some properties are guaranteed to always have the same type and format:
• Ids are always 64 bit integers
• Enums are always strings
• Timestamps are always strings, in ISO 8601 format YYYY-MM-DDTHH:MM:SSZ
• Dates have the format YYYY-MM-DD
• Times are always expressed in UTC
• Float, double or decimal values are always strings (e.g. “10.50”)
• Countries are denominated by two-letter ISO 3166 codes (e.g. “US”)
• Currencies are denominated by three-letter ISO 4217 codes (e.g. “USD”)

Endpoints

Example: # request curl http://localhost:4000/api/v1/session.create \ -u PUBLIC_KEY:SECRET # response { "id": 123, "token": "i_dI5hs7m..." } Request properties:
callback_url: string (optional)
face_verification: boolean (optional)
reference: string (optional)
Example: # request curl http://localhost:4000/api/v1/session.get \ -u PUBLIC_KEY:SECRET \ -d @- << EOF { "id": 123 } EOF # response { "id": 123, "created": "2024-01-27T00:00:00Z", "expires": "...", "state": "CREATED", "reference": "...", "user_ip": "...", "user_agent": "...", "given_names": "...", "surname": "...", "nationality": "...", "sex": "...", "date_of_birth": "...", "personal_number": "...", "document_type": "...", "document_number": "...", "expiry_date": "...", "issuing_country": "...", "issuer": "...", "portrait": "...", "face": "..." } Request properties:
id: integer (required)
Example: # request curl http://localhost:4000/api/v1/session.state \ -u PUBLIC_KEY:SECRET \ -d @- << EOF { "id": 123 } EOF # response { "state": "CREATED" } Request properties:
id: integer (required)