Need to Know

Request Validation

Synctera will not correct your requests other than for potential abuse / sanitization. You will need to validate and clean your input to ensure that your customer information is usable for features like KYC or mailing physical cards.

Environments

Base URLs

The base URL for your request determines whether the request goes to the Synctera sandbox or, when you’ve rolled your code out for real, to the Synctera production environment where your requests will transact business in the real world.

Use the sandbox base URL to make requests of the sandbox, and the production base URL to make requests of the real Synctera platform.

The examples in the Guides assume that you have set an environment variable baseurl, e.g.

export baseurl=https://api-sandbox.synctera.com

You also need to set apikey, see the Authentication section for more details.

Sandbox

You can experiment with our APIs in the Synctera sandbox, which is self-contained and has no interaction with the real world. You can use our sandbox to test our underlying services, accessing our vendors’ sandboxes as necessary when using their services. You’ll need an API key to authorize requests to the sandbox. If you don’t have one:

1. Switch to your Sandbox workspace using the workspace selector at the top of the screen
2. In the "Welcome to your Sandbox" view, click "Generate", then click the Copy icon to copy the key
3. Save the key by pasting it somewhere you can later retrieve it

Authentication

You authenticate each request by presenting your API key in the request header.

Authorization: Bearer {API_KEY}

For example, the beginning of a request using a fictitious key:

curl https://api-sandbox.synctera.com/v0/customers \
  -H 'Authorization: Bearer 476d901b4-a264a79-9db9-96d3dfaafb732'

The examples in the Guides assume that you have set an environment variable apikey, e.g.

export apikey=476d901b4-a264a79-9db9-96d3dfaafb732

You also need to set baseurl, see the Environments section for more details.

Idempotency

All of our API endpoints support idempotency, in which a request defines a state, not an action. If you repeat an idempotent request through accident or because you're unsure if an earlier request made it through, the repeated requests won't accumulate with unintended results. If you repeat an idempotent request three times to credit an account with $30, for example, you won't accidentally credit $90, you will credit the intended $30.

The response for any request made with an idempotency header is cached, and a subsequent request with the same idempotency key will return the cached response, including the initial response status code. The exceptions are requests that returns a 500-series status code (since they may not have been fully executed) and requests that are rate-limited and return a 429 status code. In these two cases, a repeat of the request with the same idempotency key will re-execute the request and not return a cached response.

Our endpoints support idempotency as defined in the IETF draft specification. To send an idempotent request, add the header Idempotency-Key: {KEY} to your request, where {KEY} is an arbitrary unique value that you define. Add the same header and key value to each repeated idempotent request.

Each idempotency key and any resulting cached responses persist for 7 days and then disappear.

An example of a cURL request using an idempotent request header with an example key value of 259:

curl -X POST https://api-sandbox.synctera.com/v0/customers \
  -H 'Idempotency-Key: 259'

Response Codes

Requests to our APIs return standard HTTP status codes (described here) often accompanied by additional data. All are formatted as JSON.

• 2xx codes indicate success and are often accompanied by response parameters generated by endpoint service.
• 4xx codes indicate request failure due to missing or erroneous request information.
• 5xx codes indicate an error in endpoint service.

OpenAPI Specification

You can download the Synctera OpenAPI schema decribing our API surface below.

Download

This schema can be used with the various openapi tools like openapi generator.

Using openapi generator, you can generate a client library to interact with Synctera. Below is an example to generate a java client library using openapi generator.

java -jar openapi-generator-cli-6.0.0-20211025.061654-22.jar generate -i synctera_openapi.json -g java -o ./java_client