Recipients API

The Recipients API is meant for manipulating the Recipient resource and related resources stored in Agillic. The Recipients API is recipient-centric, which means that all methods are focused on operations in a Recipient context. Apart from manipulating the Recipient resources with Create, Read, Update and Delete operations it also provides methods for related resources.

API Use Cases

With Recipients API you can:

  • Create, Read, Update and Delete recipients
  • Read and Achieve events
  • Evaluate promotions
  • Manipulate One To Many records
  • Read Target Groups
  • Read Communication History

Using our Discovery API you can get detailed information your Agillic instances’ Person Data, and One-To-Many recipient-centric data structures.

Examples:

In our Candy Store, we store our customers as recipients.

Create new recipient:

curl -X POST https://api-eu1.agillic.net/recipients \
    --header 'Content-Type: application/json; charset=utf-8' \
    --data   '{"personData":{"EMAIL":"ruby@sweetmail.com", "FIRSTNAME":"Ruby", ... }}'

And respond with a HTTP status code of 201 Created.

PUT can be used to both update and create an new recipients:

curl -X PUT https://api-eu1.agillic.net/recipients/ruby@sweetmail.com \
    --header 'Content-Type: application/json; charset=utf-8' \
    --data   '{"personData":{"FIRSTNAME":"Ruby J.", ... }}'

If the recipient already exist on the unique key and the update went well, the HTTP status code will be 200. If it is a create, the status code will be 201 Created as with POST. It is not possible to change the unique key with a PUT.

List recipients that use @sweetmail.com domain:

curl https://api-eu1.agillic.net/recipients?filter=EMAIL==*@sweetmail.com \
    --header 'Accept: application/json; charset=utf-8'

This will return an JSON Array of recipients matching the filter.

In case there are many recipients, the parameter objectResponse=true can be added to the call and the result will be paginated and the format will be as described on Pagination

Show PURCHASES of a recipient, stored in a One-to-Many Table:

curl https://api-eu1.agillic.net/recipients/yellow@sweetmail.com/oneToManyTables/PURCHASES \
    --header 'Accept: application/json; charset=utf-8'

Delete PURCHASES that have IDs 300 and 301:

curl -X POST https://api-eu1.agillic.net/recipients/green@sweetmail.com/oneToManyTables/PURCHASES/:batchDeleteRecords \
    --header 'Content-Type: application/json; charset=utf-8' \
    --header 'Accept: application/json' \
    --data   '["300", "301"]'

Achieve event "Share offer on Facebook":

curl -X POST https://api-eu1.agillic.net/recipients/blue@sweetmail.com/events/fb/:achieveEvent \
    --header 'Accept: application/json; charset=utf-8'

Note that these operations are recipient-specific, meaning they only modify records in the scope of one recipient.

Using Recipient ID in path resources

All endpoints that contain the {recipientId} path expression can either use the system default Recipient Id or use any other unique Person Data. Unique Person Data fields and the Instance’s Recipient Id can be configured per instance, so the usable fields will vary.

To query a recipient using a unique person data field other than the Recipient Id, you must specify which field is being used, with the format unique_pd_field=value.

So if your Instance has the Recipient Id CUSTOMER_ID, and a unique Person Data field EMAIL, you can implement api calls in the following formats:

Use the Recipient Id, CUSTOMER_ID, as the assumed path identifier:

GET /recipients/10256

Use the unique Person Data field EMAIL, which requires we specify the field name since it is not the Recipient Id. This format is also valid for the Recipient Id field, but not required.

GET /recipients/EMAIL=blue@sweetmail.com
GET /recipients/CUSTOMER_ID=10256

If you are planning to change your instance’s Recipient ID, be sure to update API call paths, either using the new Recipient Id values, or designating the field used with the format unique_pd_field=value

API Documentation