Extensions API
Page Contents
The Extensions API is designed for developers to have as much flexibility as possible and make integrations from external systems simple. This API accepts the 4 standard HTTP methods and supports all headers, parameters, paths, and request bodies. All data parsing and writing towards the Agillic Recipient Database as a result of an Extensions API call is handled in the call’s specified HTTP Extension.
The Extensions API can only be used in conjunction with a HTTP Extension. Therefore we highly recommend reading that documentation too, before getting started.
Secure Endpoint (Recommended)
If the external system calling this API can implement authentication, this is the endpoint to use.
This API call can only trigger extensions with the configuration @open:"false", otherwise the response will be 403.
Base URL:
https://api-eu1.agillic.netSupported methods:
GET,PUT,POST,DELETEPath:
/extensions/secure/<extensionId>/<path>extensionIdis the@idconfiguration required for this API. If the Http Extension doesn’t exist, the call will return 404.- The
pathis the optional path which provides any relevant information as input to the Extension. For example, the path could contain an email address, or anything else that can be useful as input for the HTTP Extension. - Any body, query parameters, or headers can be provided and used as input to the HTTP Extension.
Example API Call
See example HTTP Extension code in our Extensions example section.
Open Endpoint
If the external system calling this API cannot implement authentication, this is the endpoint to use. This API call can only trigger extensions with the configuration @open:"true" otherwise the response will be 403.
The Open Endpoint Extensions API should never be called directly on website’s client-side, or be utilized to extract recipient data from the instance.
Base URL:
https://extensions-eu1.agillic.netMethods Supported:
GET,PUT,POST,DELETEPath:
/extensions/open/<customerId>/<extensionId>/<path>extensionIdis the@idconfiguration required for this API. If the Http Extension doesn’t exist, the call will return404.customerIdidentifies your Agillic instance. There’s a separate id for your Staging and Production environments.
Contact Agillic Support to get your staging and production instances’ customerIds
pathagain is the optional path which provides any relevant information to the HTTP Extension.- Any body, query parameter, or headers can be provided and used as input to the HTTP Extension.
Example API Call
See example Http Extension code in our Extensions example section.
Asynchronous Configuration
The Extensions APIs support asynchronous responses, enabled in each Http Extension if the configuration @async:"true" is set. If the extension configuration is @async:"false", or not present, the calls will return the Http Extension’s custom response when completed.
With @async configuration enabled in the Http Extension, the above secure or open Extensions API call will return the status code 202 with an application/json body containing a queueId:
202
{"queueId":"8c63adb3-1389-4845-90e7-6085edf8c78c"}To check the status:
Each call uses its respective Base URL.
For calls made with the Secure Endpoint:
GET https://api-eu1.agillic.net/extensions/status/secure/<queueId>- Requires authentication
For calls made with the Open Endpoint:
GET https://extensions-eu1.agillic.net/extensions/status/open/<customerId>/<queueId>- Requires the same
customerIdused to generate thequeueId.
The status endpoints will return:
- The Http Extension’s expected response if the execution is complete.
- The same as the original response if the extension has not completed executing (
202withqueueIdin body). 404if thequeueIdis unknown.400if the extension exceeds a timeout limit, set as 1 minute. Note that the execution is not actually killed, so this response could be replaced later by the extension’s result if it ends up being completed.
The standalone does not support testing the asynchronous configuration. Therefore, this would need to be tested on your Staging environment.
Get started
See our Extensions example section for: