Skip to content

Customers – API methods 

Using API, you can automate adding, obtaining and changing your customers data. 

  1. POST – Adding information about a new customer and updating existing data. 
  2. GET {id} – Obtaining information about the client using the ID number assigned to him/her. 
  3. GET {email} – Obtaining information about the customer using the email address assigned to him/her. 
  4. GET {phone} – Obtaining information about the customer using the telephone number assigned to him/her. 
  5. GET {crmId} – Obtaining information about the customer using the CRM ID number assigned to him/her. 

POST method – adding customer information 

What data actions can you perform with this method? 

  • Add – Creating a customer profile in ExpertSender and adding a set of data about him/her. 
  • Update – Updating the data of a customer who is already in the platform. 
  • AddOrUpdate – Creating a client in ExpertSender or updating their data if they are already present in the platform. 

POST method – request

To send a request using this method, it must contain: 

  1. Server address (endpoint): https://api.ecdp.app/customers 
  2. Parameters:  
Parameter Type Category Description 
x-api-key string header Your API key, which you can find in Settings > API. 
mode string body Add, Update, AddOrUpdate – select one of the actions you want to perform on the data. 
matchBy string body Email, PhoneNumber, CrmId, GUID, VisitorId; select the data by which the customer should be identified, according to the information in Settings > Customers > Default identification field. 

Other parameters you can add to your request: 

Parameter Type Max character countDescription  
emailstring 320Customer’s email address; required, if the email address is set in a business unit as the default matching mode in Settings > Customers
phone* string 20Customer’s telephone number (string without spaces); required, if the phone number is set in a business unit as the default matching mode in Settings > Customers
crmId* string 128Customer CRM ID number; required, if the CRM ID is set in a business unit as the default matching mode in Settings > Customers
visitorIdstring38A unique number assigned to every visitor who browses your website
firstName string 256Customer’s first name 
lastName string 256Customer’s last name 
dateOfBirth string($date-time)  Customer’s date of birth in the format: 2023-07-25T12:35:54.712Z, where T separates the date from the time and denotes the long time format, containing seconds, and Z denotes UTC time. 
gender string  Customer’s gender: Male, Female, NotSpecified 
customAttributes  Customer attributes; includes an additional set of parameters >>> see table below 
consentsData  Consent data; includes an additional set of parameters >>> see table below 

The customAttributes and consentsData parameters also have their own parameters that will allow you to add or obtain more detailed information. 
 
For customAttributes (customer features) these are: 

Parameter Type Max character countDescription 
name* string 256Customer attribute name; a mandatory parameter when you want to add or obtain information about non-standard attributes
value string Customer attribute value 

For consentsData (data regarding consents) these are: 

Parameter Type Description 
consents  Detailed consent data; includes an additional set of parameters >>> see table below 
force boolean Indicates whether another confirmation link is to be sent for consents marked as “AwaitingConfirmation”, regardless of whether it was sent earlier. 
confirmationMessageId integer($int32) Confirmation message ID 

For consents these are: 

Parameter Type Description 
id* integer($int32) Single consent ID; a mandatory parameter when you want to add or obtain consent information. 
value* string Consent confirmation status; possible consent values are False, AwaitingConfirmation, True; a mandatory parameter when you want to add or obtain information about consent. 
When you select AwaitingConfirmation, an email will be sent to the customer confirming consent. 

POST method – request body 

Below you can see an example request body used when you want to add (Add) a customer to the database: 

{
  "mode": "Add",
  "matchBy": "Email",
  "data": [
    {
      "email": "string",
      "phone": "string",
      "crmId": "string",
      "firstName": "string",
      "lastName": "string",
      "dateOfBirth": "2023-07-26T12:28:33.490Z",
      "gender": "Female",
      "customAttributes": [
        {
          "name": "string",
          "value": "string"
        }
      ],
      "consentsData": {
        "consents": [
          {
            "id": 0,
            "value": "False"
          }
        ],
        "force": true,
        "confirmationMessageId": 0
      }
    }
  ]
}

When updating customer data, change the “mode” parameter to “Update”

If you do not know whether a given customer is already in the database and you want to add his or her data, change the “mode” parameter to “AddOrUpdate”

POST request response codes

201: Created

The request has been created.

400: Bad request

The request was not processed. The reason is usually a missing or incorrect parameter, such as email, phone, etc. Sample response syntax:

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "errors": [
    "string"
  ]
}

401: Unauthorized

The request was missing an API key or you are requesting access to information that you do not have permission to access. Sample response syntax:

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

GET method – obtaining information about the customer 

The GET method is used to obtain information about the client from the ExpertSender platform. For a correctly formulated API request, you will receive a response with a ‘read-only’ status. 
 
You have 4 types of GET methods at your disposal, which differ only in the information required to send the query. 

GET{id} method using customer ID number 

The method is used to obtain information about the client using the ID number assigned to him/her. To send a query using this method, it must contain: 

  1. Server address (endpoint): https://api.ecdp.app/customers/id/{id} 
  2. Customer ID: ID number of the customer whose data you want to obtain. 
  3. API key: Your API key, found in Settings > API. 

The correct API query for client ID 12 looks like this: https://client.ecdp.app/customers/id/{12}

GET{id} request response codes

200: Success

The query was processed, the server returned a response. Sample response syntax:

{
  "status": 0,
  "data": {
    "email": "string",
    "phone": "string",
    "crmId": "string",
    "firstName": "string",
    "lastName": "string",
    "dateOfBirth": "2023-07-25T13:58:16.339Z",
    "gender": "Female",
    "rfmSegment": "string",
    "totalSpent": 0,
    "totalOrders": 0,
    "totalOrderReturns": 0,
    "avgOrder": 0,
    "avgPricePoint": 0,
    "lastOrder": "2023-07-25T13:58:16.339Z",
    "avgTimeBetweenOrdersInDays": 0,
    "currencySymbol": "string",
    "customAttributes": [
      {
        "name": "string",
        "value": "string"
      }
    ],
    "consentsData": {
      "consents": [
        {
          "id": 0,
          "value": "False"
        }
      ]
    }
  }
}

401: Unauthorized

The request was missing an API key, or you are requesting access to information that you do not have permission to access. Sample response syntax:

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

404: Not found

The data you are looking for is not on the server. Sample response syntax: 

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

GET{email} method using the customer’s email address 

The method is used to obtain information about the customer using the email address assigned to him/her. To send a query using this method, it must contain: 

  1. Server address (endpoint): https://api.ecdp.app/customers/email/{email} 
  2. Customer Email: Customer’s email address. 
  3. API key: Your API key, found in Settings > API. 
     
    The API query template for a customer with the email address adam@email.com is as follows: https://client.ecdp.app/customers/email/{adam@email.com} 

GET{email} request response codes 

200: Success

The query was processed, the server returned a response. Sample response syntax:

{
  "status": 0,
  "data": {
    "email": "string",
    "phone": "string",
    "crmId": "string",
    "firstName": "string",
    "lastName": "string",
    "dateOfBirth": "2023-07-25T14:02:39.444Z",
    "gender": "Female",
    "rfmSegment": "string",
    "totalSpent": 0,
    "totalOrders": 0,
    "totalOrderReturns": 0,
    "avgOrder": 0,
    "avgPricePoint": 0,
    "lastOrder": "2023-07-25T14:02:39.444Z",
    "avgTimeBetweenOrdersInDays": 0,
    "currencySymbol": "string",
    "customAttributes": [
      {
        "name": "string",
        "value": "string"
      }
    ],
    "consentsData": {
      "consents": [
        {
          "id": 0,
          "value": "False"
        }
      ]
}

401: Unauthorized

The request was missing an API key or you are requesting access to information that you do not have permission to access. Sample response syntax:

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

404: Not found

The data you are looking for is not on the server. Sample response syntax:

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

GET{phone} method using the customer’s phone number 

The method is used to obtain information about the client using the phone number assigned to him/her. To send a query using this method, it must contain: 

  1. Server address (endpoint): https://api.ecdp.app/customers/phone/{phone} 
  2. Customer Phone: Customer’s phone number. 
  3. API key: Your API key, found in Settings > API. 

A valid API query for a customer with phone number 123 456 789 will look like this: https://client.ecdp.app/customers/phone/{123456789} 

GET{phone} response codes 

200: Success

The query was processed, the server returned a response. Sample response syntax:

{
  "status": 0,
  "data": {
    "email": "string",
    "phone": "string",
    "crmId": "string",
    "firstName": "string",
    "lastName": "string",
    "dateOfBirth": "2023-07-26T07:02:46.313Z",
    "gender": "Female",
    "rfmSegment": "string",
    "totalSpent": 0,
    "totalOrders": 0,
    "totalOrderReturns": 0,
    "avgOrder": 0,
    "avgPricePoint": 0,
    "lastOrder": "2023-07-26T07:02:46.313Z",
    "avgTimeBetweenOrdersInDays": 0,
    "currencySymbol": "string",
    "customAttributes": [
      {
        "name": "string",
        "value": "string"
      }
    ],
    "consentsData": {
      "consents": [
        {
          "id": 0,
          "value": "False"
        }
      ]
    }
  }
}

401: Unauthorized

The request was missing an API key or you are requesting access to information that you do not have permission to access. Sample response syntax:

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

404: Not found

The data you are looking for is not on the server. Sample response syntax:

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

GET{crmId} method using the customer’s CRM ID number 

The method is used to obtain information about the customer using the CRM ID number assigned to him/her. To send a query using this method, it must contain: 

  1. Server address (endpoint): https://api.ecdp.app/customers/crmId/{crmId} 
  2. Customer crmId: Customer’s CRM number. 
  3. API key: Your API key, found in Settings > API.

GET{crmId} query response codes

200: Success

The query was processed, the server returned a response. Sample response syntax:

{
  "status": 0,
  "data": {
    "email": "string",
    "phone": "string",
    "crmId": "string",
    "firstName": "string",
    "lastName": "string",
    "dateOfBirth": "2023-07-26T07:07:53.146Z",
    "gender": "Female",
    "rfmSegment": "string",
    "totalSpent": 0,
    "totalOrders": 0,
    "totalOrderReturns": 0,
    "avgOrder": 0,
    "avgPricePoint": 0,
    "lastOrder": "2023-07-26T07:07:53.146Z",
    "avgTimeBetweenOrdersInDays": 0,
    "currencySymbol": "string",
    "customAttributes": [
      {
        "name": "string",
        "value": "string"
      }
    ],
    "consentsData": {
      "consents": [
        {
          "id": 0,
          "value": "False"
        }
      ]
    }
  }
}

401: Unauthorized

The request was missing an API key or you are requesting access to information that you do not have permission to access. Sample response syntax:

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

404: Not found

The data you are looking for is not on the server. Sample response syntax:

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}