API

Table of Contents

Authentication
Customers API
Event API
- Create Customer Event
  - Headers
  - Request body

Authentication #

To use the Retainly API endpoint, you will need to set the API KEY and API KEY SECRET parameters in the request header. You can find these parameters by following these steps:

Log in to your Retainly account
Navigate to the “Integrations” page by clicking on the “Sidebar” menu and selecting “Integrations”
Find the “Retainly API” integration and click “Integrate”
On the opened page, you will find your API KEY and API KEY SECRET.
Copy these values and insert them into the request header of your API call.

IMPORTANT: It is important to keep these parameters secure and not share them with anyone. To ensure the security of your account, you should keep these values confidential.

Customers API #

Create/Update Customer endpoint #

To use the full functionality of Retainly, you will need to import your customer database into the Retainly app. The best way to do this is by using our API. You can send your customer data in any format, but it must contain the “id” field, which represents a unique customer id.

If you enter a new “id” that has not been previously added, a new customer will be created in the database. If you enter an id that has already been added, the customer’s data with this id will be updated with the new values.

To make a request to the API, you can use the following parameters:

Headers #

Header	Decription
key*	Workspace key to identifying workspace to make changes. Correspond to API KEY field value.
secret*	API KEY SECRET field value.

* – required

Request body #

Parameter	Type	Description
customers*	array[object]	Array with objects. Object keys are customer fields. – required – The array can not be empty. – The maximum number of customers in the array is 10000. – Each object (customer) should have the parameter id*. – Customer can have a maximum of 500 customer fields. – Customer can’t have more than 15 attributes with type array. – Array items could have only 1 nesting layer of arrays in the attribute value. – Attribute value could not be an associative array. – The maximum length for string attributes value is 1000 chars.

* – required

Method: POST
Base URL: https://track.retainly.app/customers
Request body: application/json

Important: Remember to include the “id” field in your request body to ensure that your customer data is properly imported into the Retainly app. You can only send one customer at a time

HTTP Request Example

Note: change key and secret values to your own values

curl -X 'POST' \
  'https:/track.retainly.app/customers' \  
  -H 'accept: application/json' \  
  -H 'key: your_api_key' \  
  -H 'secret: your_api_secret' \  
  -H 'Content-Type: application/json' \  
  -d '{
        "customers":[
          {
            "id":1,
            "customer_field_string":"value", 
            "customer_field_boolean":true, 
            "customer_field_number":1, 
            "customer_field_date_time":"2022-02-25T21:00:00.000Z", 
            "customer_field_date":"2022-02-25", 
            "customer_field_array_with_linears":[
              "one", 
              "two", 
              "three"
            ] 
          },
          {
            "id":2,
            "customer_field_string":"value", 
            "customer_field_boolean":true, 
            "customer_field_number":1, 
            "customer_field_date_time":"2022-02-25T21:00:00.000Z", 
            "customer_field_date":"2022-02-25", 
            "customer_field_array_with_objects":[
              {
                "object_field_string":"value", 
                "object_field_boolean":true,
                "object_field_number":1, 
                "object_field_date_time":"2022-02-25T21:00:00.000Z", 
                "object_field_date":"2022-02-25", 
                "object_field_array_with_nested_array":
                  [
                    {
                      "nested_array_object_field_string":"value",
                      "nested_array_object_field_boolean": true 
                    }
                  ] 
              },
              {
                "object_field_string":"value", 
                "object_field_boolean":false,
                "object_field_number":2, 
                "object_field_date_time":"2022-02-25T21:00:00.000Z", 
                "object_field_date":"2022-02-25"
              } 
            ]
          } 
        ]
      }'

Responses

Status code	Description	Schema
200	Success	`"string"`
422	Validation errorFor example missing required parameters, incorrect values, or syntax errors.	`{ "detail": [ { "loc": [ "string", 0 ], "msg": "string", "type": "string" } ] }`
403	Authentication error	`{ "message": "forbidden" }`

Create and update customer array data #

This endpoint allows you to create or update customers’ array items. To identify customers, you should set the field “customer_id” – unique id for all customers. If there is a customer in the workspace with the specified unique id and the field “id” for the array item is missed the new items will be added to the array or the array item data would be updated with a new one by the field “id” in the array item. If the customer with a specified id does not exist, it will be created with new input array data. Set field id into array item data to update or delete array item later.

To create and update customer array data, you can use the following parameters:

Headers #

Header	Decription
key*	Workspace key to identifying workspace to make changes. Correspond to API KEY field value.
secret*	API KEY SECRET field value.

* – required

Request body #

Parameter	Type	Description
records*	array[object]	Array with objects. required – The array can not be empty. – The maximum number of customers in the array is 10000. – Each object should have: — customer_id* – unique customer id; — field* – customer field array key (Use value from the Field settings page → Tab Array →column field or other field key should becreated) — data* – array with objects – items that should be added or updated in the customer array. – Array items could have only 1 nesting layer of arrays in the attribute value. – Attribute value could not be an associative array. – The maximum length for string attributes value is 1000 chars.

* – required

Method: POST
Base URL: https://track.retainly.app/arrays
Request body: application/json

HTTP Request Example

curl -X 'POST' \
  'https://track.retainly.app/arrays' \  
  -H 'accept: application/json' \  
  -H 'key: your_api_key_secret' \  
  -H 'secret: your_api_secret' \ 
  -H 'Content-Type: application/json' \  
  -d '{
        "records":[
          { 
            "customer_id":1, 
            "field": "purchases", 
            "data":[
              {
                "id":1,
                "amount":123,
                "products":[
                  {
                    "name":"apple"
                  }, 
                  {
                    "name":"banana" 
                  }
                ] 
              },
              {
                "id":2,
                "amount":111,
                "products":[
                  {
                    "name":"apple"
                  }, 
                  {
                    "name":"banana" 
                  }
                ]
              }
            ]
          },
          {
            "customer_id":2,
            "field":"booking",
            "data":[
              {
                "booking_number":123
              }, 
              {
                "id":2,
                "booking_number":123 
              }
            ] 
          }
        ] 
      }'

Delete Customers #

This endpoint allows you to delete customers in the workspace. To identify a customer for deletion, use a unique customer id from the customer field ‘id’. You will not make an error if the customer with a specified id does not exist.

To delete customers from the workspace, you can use the following parameters:

Headers #

Header	Decription
key*	Workspace key to identifying workspace to make changes. Correspond to API KEY field value.
secret*	API KEY SECRET field value.

* – required

Request body #

Parameter	Type	Description
customers_ids*	array[mixed]	Array with customer unique ids. – The array can not be empty. – The maximum count of customers to delete for one request is 10000.

*-required

Method: DELETE
Base URL: https://track.retainly.app/customers
Request body: application/json

HTTP Request Example

curl -X 'DELETE' \
  'https://track.retainly.app/customers' \  
  -H 'accept: application/json' \  
  -H 'api-key: your_api_key' \  
  -H 'api-secret: your_api_secret' \  
  -H 'Content-Type: application/json' \  
  -d '{
        "customers_ids":[
          01010011234,
          01010011235,
          01010011236
          ]
        }'

Delete Customers’ array items #

This endpoint allows you to delete customer arrays’ items. You will not make an error if the customer with a specified id does not exist or the array field does not exist.

To delete customers` array items, you can use the following parameters:

Headers #

Header	Decription
key*	Workspace key to identifying workspace to make changes. Correspond to API KEY field value.
secret*	API KEY SECRET field value.

* – required

Request body

Parameter	Type	Description
records*	array[object]	Array with objects. – Each object should have: – customer_id* – unique customer id; – field* – customer field array key (Use value from the Field settings page → Tab Array →column field or other field key should becreated); – ids* – array with ids of array items. – The array can not be empty. – The maximum count of objects to delete for one request is 10000.

* – required

Method: DELETE
Base URL: https://track.retainly.app/arrays
Request body: application/json

HTTP Request Example

curl -X 'DELETE' \
  'https://track.retainly.app/arrays' \  
  -H 'accept: application/json' \  
  -H 'api-key: your_api_key' \  
  -H 'api-secret: your_api_secret' \  
  -H 'Content-Type: application/json' \  
  -d '{
        "records":[
          {
            "customer_id":1,
            "field":"purchases",
            "ids":[
              1,
              2 
            ]
            },
          {
            "customer_id":1,
            "field":"purchases",
            "ids":[
              2
            ]
          }
        ]
      }'

Event API #

Create Customer Event #

Endpoint allows you to create customers’ events and run a workflow that starts with an event node.

Note: this trigger starts all workflows in the workspace with an event set in the request body.

Headers #

Header	Decription
key*	Workspace key to identifying workspace to make changes. Correspond to API KEY field value.
secret*	API KEY SECRET field value.

* – required

Request body #

Parameter	Type	Description
customer_id*	mixed	Customer unique id in system.
event*	string	Event name Maximum 50 symbols.
data	object	– Object with key – value pairs, that need to be added to customers’ events and be added to customer attributes in workflow. Used in notification templates. It doesn’t change customers attributes. – Attribute value could not be an associative array. – The maximum length for string attributes value is 1000 chars. – Maximum 50 fields.

* – required

Method: POST
Base URL: https://track.retainly.app/events
Request body: application/json

HTTP Request Example

curl -X 'POST' \
  'https://track.retainly.app/events' \  
  -H 'accept: application/json' \  
  -H 'api-key: your_api_key' \  
  -H 'api-secret: your_api_secret' \  
  -H 'Content-Type: application/json' \  
  -d '{
        "customer_id" : "unique customer id", 
        "event" : "event",
        "data":{
          "param1":"value1", 
          "param2":"value2", 
          "nested_event_array_param":[
            {
              "nested_array_param1":"value1"
            }, 
            {
              "nested_array_param1":"value2" 
            }
          ] 
        }
      }'

Responses

Status code	Description	Schema
200	Success	No response body
400	Request errorFor example: Invalid JSON data in request body: Syntax error	string
422	Validation errors. For example, incorrect authentication parameters, missing required parameters, or incorrect values.	`object : { "errors": { "error_name_1": [ "error message 1", "error message 2" ], "error_name_2": [ "error message 1", ] } }`

For Beginners

For Advanced

For Developers

Authentication #

Customers API #

Create/Update Customer endpoint #

Headers #

Request body #

Create and update customer array data #

Headers #

Request body #

Delete Customers #

Headers #

Request body #

Delete Customers’ array items #

Headers #

Event API #

Create Customer Event #

Headers #

Request body #

Documentation

Authentication #

Customers API #

Create/Update Customer endpoint #

Headers #

Request body #

Create and update customer array data #

Headers #

Request body #

Delete Customers #

Headers #

Request body #

Delete Customers’ array items #

Headers #

Event API #

Create Customer Event #

Headers #

Request body #

Share :