Customers – API methods - ExpertSender Help Center

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

POST – Adding information about a new customer and updating existing data.
GET {id} – Obtaining information about the client using the ID number assigned to him/her.
GET {email} – Obtaining information about the customer using the email address assigned to him/her.
GET {phone} – Obtaining information about the customer using the telephone number assigned to him/her.
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:

Server address (endpoint): https://api.ecdp.app/customers
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 count	Description
email*	string	320	Customer’s email address; required, if the email address is set in a business unit as the default matching mode in Settings > Customers
phone*	string	20	Customer’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	128	Customer CRM ID number; required, if the CRM ID is set in a business unit as the default matching mode in Settings > Customers
visitorId	string	38	A unique number assigned to every visitor who browses your website
firstName	string	256	Customer’s first name
lastName	string	256	Customer’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 count	Description
name*	string	256	Customer 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:

Server address (endpoint): https://api.ecdp.app/customers/id/{id}
Customer ID: ID number of the customer whose data you want to obtain.
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:

Server address (endpoint): https://api.ecdp.app/customers/email/{email}
Customer Email: Customer’s email address.
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:

Server address (endpoint): https://api.ecdp.app/customers/phone/{phone}
Customer Phone: Customer’s phone number.
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:

Server address (endpoint): https://api.ecdp.app/customers/crmId/{crmId}
Customer crmId: Customer’s CRM number.
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"
}