Extensions API

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.net

Supported methods:

GET,PUT,POST,DELETE

Path:

/extensions/secure/<extensionId>/<path>
  • extensionId is the @id configuration required for this API. If the Http Extension doesn’t exist, the call will return 404.
  • The path is 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.net

Methods Supported:

GET,PUT,POST,DELETE

Path:

/extensions/open/<customerId>/<extensionId>/<path>
  • extensionId is the @id configuration required for this API. If the Http Extension doesn’t exist, the call will return 404.
  • customerId identifies 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

  • path again 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>

For calls made with the Open Endpoint:

GET https://extensions-eu1.agillic.net/extensions/status/open/<customerId>/<queueId>
  • Requires the same customerId used to generate the queueId.

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 (202 with queueId in body).
  • 404 if the queueId is unknown.
  • 400 if 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: