Fourthline API Reference

Welcome to Fourthline's API Reference!

To learn to use and get the most out of this documentation, check out the video tour.

Fourthline API

Our API is organized around REST. It has predictable resource-oriented URLs, accepts and returns JSON-encoded responses.

It uses:

All API requests must be made over HTTPS. Requests made over plain HTTP will fail.

All responses are returned immediately (asychronously), while our system continues processing the request.


Our API uses bearer token authentication. Every request you make must include an access token in the Authorization header.

To request access tokens, you need your Fourthline API key to make Get access token requests.



You can test our API in the sandbox environment, which is as similar as possible to production for controlled testing, but not automated testing.


When you go live with your integration, address the production environment.
You can't test in the production environment.

Response codes

We use conventional HTTP response codes to indicate the success or failure of an API request.
In general, codes in the:

  • 2XX range indicate success
  • 4XX range indicate an error for the reason provided, e.g. a required parameter was omitted
  • 5XX range indicate a rare Fourthline server error

Not all errors map cleanly onto HTTP response codes. If a valid request fails, e.g. because the country code is not supported, we return a 422 error.

Response codeDescription
200 OKThe request was successful.
201 CreatedThe request was successful.
202 AcceptedThe request has been accepted for processing, but processing isn't finished yet.
204 No contentThe request was successful, but the response returns no body.
400 Bad requestThe request was invalid, usually because a required parameter wasn't set.
401 UnauthorizedYour access token is invalid.
403 ForbiddenThe request is valid, but our server refuses to respond to it.
Unlike a 401 unauthorized response, you cannot solve this by authenticating.
404 Not foundThe resource you requested doesn't exist.
• Check your credentials and contact your implementation manager.
• Check your request headers.
405 Method not allowedThe HTTP method you used is not allowed for the resource, e.g. a POST request to a read-only resource.
409 ConflictWe couldn't process the request because there's a conflict in the current state of the resource, e.g. an editing conflict between multiple, simultaneous updates.
422 Unprocessable entityAt least 1 parameter is the right type but is invalid.
Troubleshooting: Check your providerProcessId.
429 Too many requestsYou have sent too many requests in too short a space of time.
5XX Server errorSomething went wrong on our side.


We provide a cURL example for each request. You can set the required and optional parameters as relevant, and then test the request from the command line.

To test our API using:

OpenAPI specification

To view the OpenAPI specification of our API:

  1. Go to
  2. Click API - V1.0.

For help getting started, contact your implementation manager.

Top of page