With our Asynchronous API you can issue API calls in rapid succession – such as from a for loop, or from a large-scale multi-threaded system – and they will all get queued to process in background, with an instant API Call ID you get back. Then, you can register a Callback Webhook which will receive the full response upon completion for each call.
The two API modes – Synchronous vs Asynchronous
You can toggle your ScaleGrowth API between Synchronous and Asynchronous modes. By default, your API is operating in the Synchronous mode.
Synchronous API
The Synchronous API is shared across all of your API User Accounts and API Clients. That is, regardless of how many API User Accounts and API Clients your team creates, the platform will only process one API request at a time.
If a second Synchronous API call is attempted while a previous Synchronous API call still hasn't finished processing, you will receive a response with HTTP Status 429 – Too Many Requests – and this error message: "Another API call is already in progress. Please try again later or use the ScaleGrowth Asynchronous API for use cases requiring parallel API calls."
Asynchronous API
For POST requests, the Asynchronous API can be enabled on a per-call basis.
For GET and DELETE requests, the Asynchronous API can be enabled on a per-API-User-Account basis. This functions as an API User Account wide toggle.
This means that you are able to toggle one of your API User Accounts to run in the Asynchronous mode, while continuing to operate another API User Account in the Synchronous mode. Or you could run your GET requests asynchronously while running your POST requests synchronously – or vice versa.
Using both in parallel
Asynchronous API calls do not affect the Synchronous API. The ScaleGrowth API will always allow the processing of 1 Synchronous API call at a time – platform-wide – regardless of whether you have Asynchronous API calls processing and regardless of their number.
Asynchronous POST requests
To issue an Asynchronous POST, you use the same exact API as you did for the Synchronous POST – and you simply add in an additional parameter "callback" with the value of the Callback URL Webhook, to which the response will be posted by the ScaleGrowth API when the processing is complete.
Please note that the value of the "callback" URL must start with "https://" and also needs to be added to the list of approved Redirect URIs under your OAuth 2.0 API Client Application:
If you issue a POST with the "callback" parameter, you will receive 2 different responses. First, the API will immediately (synchronously) respond with a Tracking Response that includes the "api_call_id" for the Asynchronous API Call.
Sample Asynchronous API Call:
% curl -H "Authorization: Bearer isyk9hsE2ToxvdHiZdbl0Gh1arwY8V" -H "Content-Type: application/json" -X POST https://example.ngrok.io/api/v1/custom_offers/1/ -d '{"offer_name":"Async API Offer Post Example", "smart_field_34": "Example Field Value", "callback": "https://www.wherever.com"}'
Please note that isyk9hsE2ToxvdHiZdbl0Gh1arwY8V above is an example value. Also, the https://example.ngrok.io/api/v1/custom_offers/1/ is an example ScaleGrowth API endpoint piped though https://ngrok.com/ for local dev testing.
Sample Tracking Response:
{"api_call_id":"3dbf59d4-dd9f-404b-974b-637a233946aa"}
Please note that 3dbf59d4-dd9f-404b-974b-637a233946aa above is an example value.
Then, once the processing completes on our end, the ScaleGrowth API will issue a POST to the specified "callback" URL – https://www.wherever.com in the example above – with the Full Response. The format of the Full Response remains the same as for the Synchronous POST before, except it will also additionally include the same exact "api_call_id" that was issued during the Tracking Response:
Sample Full Response:
{"cuid":"f81056af-1c5b-489a-ba55-3576886943b3","log":["Processing Listing 'Async API Offer Post Example' owned by the platform","Creating as a platform-owned Listing","CREATED a new platform-owned Listing","Added the Listing with the Customer Unique ID 'f81056af-1c5b-489a-ba55-3576886943b3' to Space 'Legendary Jobs'","Updating the Listing with new 'offer_name' value","Updating the platform config for 'smart_field_34' with new Option encountered: 'Example Field Value'","Updating the Listing with new 'smart_field_34' value","Updating the Listing records in your CRM database"], "api_call_id":"3dbf59d4-dd9f-404b-974b-637a233946aa"}
Please note that f81056af-1c5b-489a-ba55-3576886943b3 and 3dbf59d4-dd9f-404b-974b-637a233946aa above are both example values.
Finally, optionally, you may also include an additional "headers" parameter together with the "callback" one – whatever value you pass in via the "headers" will be sent back as "headers" during the Full Response POST that the ScaleGrowth API issues to the "callback" URL upon completion. This provides support for the use-case where your Callback Webhook requires certain headers, for example to add secure authentication for it.
As you can see, the actual API change on your end to make any API call Asynchronous should be minimal – all you need to do is add in the "callback" parameter to your existing API calls – plus an optional "headers" parameter depending on your Webhook's security model.
Asynchronous GET and DELETE requests
In case of GET requests, you have to issue a separate POST to toggle the Asynchronous mode.
To do this, simply issue a POST request to the corresponding ScaleGrowth API endpoint (without a specific SG ID) containing one of the following keys in the data of the request body:
- "callback_list" – Your callback endpoint for GET calls listing all objects (without a specific SG ID).
- "callback_get" – Your callback endpoint for GET calls retrieving a single object (with a specific SG ID).
- "callback_delete" – Your callback endpoint for DELETE calls deleting a single object (with a specific SG ID).
** - "callback_headers" – A JSON dictionary of key–value pairs to be sent as HTTP headers during the Full Response POSTs issued by the ScaleGrowth API to your callback_list or callback_get URLs. This is useful when your Callback endpoints require authentication headers or other custom headers.
** – please note that the Asynchronous DELETE functionality is disabled out of the box as a best practice for security reasons – as well as to minimize the chances of accidental irreversible bulk data erasure during API testing & development. To request the Asynchronous DELETE capability, please post under Ask SG Team in your Success Center (or reach out to your ScaleGrowth account manager if you are an Enterprise customer).
Example Request:
% curl -X POST "https://example.ngrok.io/api/v1/members/" \
-H "Authorization: Bearer isyk9hsE2ToxvdHiZdbl0Gh1arwY8V" \
-H "Content-Type: application/json" \
-d '{
"callback_list": "https://example.your-site.com/list/callback/",
"callback_get": "https://example.your-site.com/get/callback/",
"callback_delete": "https://example.your-site.com/delete/callback/",
"callback_headers": {
"Authorization": "YOUR_AUTH_EXAMPLE"
}
}'
Important Notes
If your POST includes any of callback_list, callback_get, or callback_headers, it will be treated as a Callback Configuration POST.
You cannot combine Callback Configuration with object creation or update data in the same request – other fields will be ignored.
All callback URLs must:
- Start with https://
- Be listed as Approved Redirect URIs under your OAuth 2.0 API Client Application
Disabling Callbacks
To disable callbacks, issue another Callback Configuration POST and set the fields to empty strings:
% curl -X POST "https://example.ngrok.io/api/v1/members/" \
-H "Authorization: Bearer isyk9hsE2ToxvdHiZdbl0Gh1arwY8V" \
-H "Content-Type: application/json" \
-d '{
"callback_list": "",
"callback_get": "",
"callback_delete": ""
}'
This will revert any future API calls back to the Synchronous API mode.
Need more help?
If you have additional questions about using the Asynchronous API, please post them under Ask SG Team in your Success Center – we are happy to help!
