Integrate Synthetiq's API to connect your systems to document processing
Overview Of Synthetiq's API
Synthetiq's API is organized around REST and uses built-in HTTP features, standard response codes, authentication and verbs, allowing for quick implementation with standard HTTP packages used in all languages. The API accepts requests with a JSON body and returns JSON responses.
API Authentication
Your organization's API credentials can be viewed and managed by navigating to Developers > API Credentials in Synthetiq's platform.
To authenticate a request, you must include your api-key in the request header for all requests.
| Key | Type | Required/Optional | Description |
|---|---|---|---|
api-key | String | Required | Identifier specific to your organization |
IP Address Whitelist
You can whitelist specific IP addresses to increase security and grant network access only to specific IP addresses. This is an additional security option that helps reduce risks in the event that your API Key were to become compromised.
To set up IP address whitelisting navigate to General Settings > Developers > IP Address Whitelisting. Please note that no IP address check will be performed unless this has been set up (i.e. by default, all traffic is allowed).
Response Status Codes
Synthetiq's API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 200 range indicate success, codes in the 400 range indicate an error with the request and codes in the 500 range indicate an error with the server.
| Status Code | Status Message | Description |
|---|---|---|
200 | Success | The request processed successfully |
400 | Bad request | The request was incorrectly formed |
401 | Unauthorized | The authentication credentials were incorrect |
404 | Resource not found | The requested resource cannot be found |
500 | Internal server error | There was an error on the server |
Rate Limits
The Synthetiq API prioritizes stability and has safeguards to help ensure that extremely rapid bursts of incoming API requests do not prevent normal API requests from processing.
Synthetiq's API supports a maximum of 100 requests per second for each Synthetiq customer. If you exceed this rate limit, you'll begin receiving error responses with status code 429. Please treat this limit as a maximum and take care to not generate unnecessary load. If you need a higher rate limit for business reasons, please contact us.
We may reduce these rate limits to prevent abuse or, if your volume is consistently at extremely high levels, we may request that you migrate to a private server that we can optimize for your specific workload.
Rate limits ensure uptime and maximize stability.
Synthetiq's rate limits are set high enough that normal workflows should rarely exceed these limits. However, rate limits can be exceeded under occur under a variety of conditions that you should consider:
- Running migration or batch-testing operations that require many closely-spaced requests. In these cases, you should try to control the request rate on the client side using queuing or similar methods.
- Accidentally encoding API-based loops that execute constantly and indefinitely. In these cases, you should debug the logical issue on your side.
- Keeping many long-lived requests open can increase the likelihood of rate limiting. Resource-intensive API requests take longer to run and increase the risk that new requests will be rejected. We suggest profiling your Synthetiq API requests and watching for lengthy requests to help identify these potential issues.
A common technique for handling rate limits is to build in a retry mechanism for 429 status codes. This mechanism should follow an exponential back-off schedule to reduce request volume.
Idempotent Requests
Synthetiq's API supports idempotency, which lets you safely retry API requests without accidentally performing the same operation twice. This can be used to strengthen your integration with Synthetiq and reduce the risk that can occur when an API request (from you to Synthetiq) was successful but the response was disrupted in transit and therefore did not arrive.
For Example
If you make a POST request to the Extract Document API and this is performed successfully but the API response fails to deliver, you don't want to retry your request and have it accidentally create the same application again.
To ensure idempotency when making requests to Synthetiq, you need to provide an additional idempotency-key element in the header. This key should be generated by you and must be unique. The method you use for creating this key is up to you, however we suggest UUIDs or other types of random strings with enough length to avoid collisions.
Synthetiq's idempotency works by saving the resulting status code and the body of the first request made for any given idempotency key, regardless of whether it succeeded or failed. Subsequent requests with the same key return the same result.
Keys are deleted by Synthetiq after 6 hours and a new request is generated if a key is reused after the prior key was deleted.
The POST requests in Synthetiq's API accept idempotency keys (PUT, GET and DELETE requests are idempotent by definition).