Customers – API methods - ExpertSender Help center

The API lets you automate how you add, retrieve, and update your customer data.

POST – add information about a new customer and update existing data.
GET {id} – get information about a customer using their ID number.
GET {email} – get information about a customer using their email address.
GET {phone} – get information about a customer using their phone number.
GET {crmId} – get information about a customer using their CRM ID number.

POST method – adding customer information

What can you do with this method?

Add – create a customer profile in ExpertSender and add their data.
Update – update data for a customer who’s already in the platform.
AddOrUpdate – create a customer in ExpertSender or update their data if they already exist.

Endpoint

The endpoint for POST requests is: https://api.ecdp.app/customers

Request parameters

Parameter	Required	Type	Used in	Description
x-api-key	yes	string	header	Your API key, which you can find in Settings > API.
mode	yes	string	request body	Add, Update, AddOrUpdate – choose one action you want to perform.
matchBy	yes	string	request body	Email, PhoneNumber, CrmId, GUID – choose how to identify the customer, based on your Settings > Customers > Default identification field.

Other parameters you can add to your request:

Parameter	Required	Type	Max character count	Description
email	yes	string	320	Customer’s email address – required if email is set as the default matching mode in Settings > Customers.
phone	yes	string	20	Customer’s phone number (no spaces) – required if phone is set as the default matching mode in Settings > Customers.
crmId	yes	string	128	Customer’s CRM ID number – required if CRM ID is set as the default matching mode in Settings > Customers.
visitorId	no	string	38	A unique number assigned to every visitor who browses your website.
firstName	no	string	256	Customer’s first name
lastName	no	string	256	Customer’s last name
dateOfBirth	no	string($date-time)	–	Customer’s date of birth in this format: 2023-07-25T12:35:54.712Z, where T separates date from time and Z indicates UTC time.
gender	no	string	–	Customer’s gender: Male, Female, NotSpecified
customAttributes	no			Customer attributes – see Custom attribute parameters.
consentsData	no			Consent data – see Consent data parameters.

The customAttributes and consentsData parameters have their own sub-parameters for more detailed information.

Custom attribute parameters

Parameter	Required	Type	Max character count	Description
name	yes	string	256	Customer attribute name; a mandatory parameter when you want to add or obtain information about non-standard attributes; minimum number of characters: 1
value	no	string	–	Customer attribute value

Parameter	Required	Type	Description
consents	no		Detailed consent data – see Consent parameters.
force	no	boolean	Indicates whether another confirmation link is to be sent for consents marked as “AwaitingConfirmation”, regardless of whether it was sent earlier.
confirmationMessageId	no	integer($int32)	Confirmation message ID

Parameter	Required	Type	Description
id	yes	integer($int32)	Single consent ID – required when adding or getting consent information.
value	yes	string	Consent status: False, AwaitingConfirmation, True – required when adding or getting consent information. When you select AwaitingConfirmation, we’ll send the customer a confirmation email.

Request body

Here’s an example request body for adding a customer to your 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
      }
    }
  ]
}

To update customer data, change the “mode” parameter to “Update”.

If you’re not sure whether a customer already exists and want to add their data, change the “mode” parameter to “AddOrUpdate”.

Response codes

201: Created

Your request was created.

400: Bad request

We couldn’t process your request. This usually means a parameter is missing or incorrect (like email, phone, etc.).

Sample response:

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

401: Unauthorized

Your request was missing an API key or you don’t have permission to access this information

Sample response:

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

GET method – getting customer information

Use the GET method to retrieve customer information from ExpertSender. When your API request is properly formatted, you’ll get a response with ‘read-only’ status.

You have 4 types of GET methods available. They only differ in what information you need to send the request.

GET{id} method using customer ID

This method gets customer information using their ID number.

Endpoint

The endpoint for GET{id} requests is: https://api.ecdp.app/customers/id/{id}

Request parameters

Parameter	Required	Type	Used in	Description
id	yes	string	URL path	The ID number of the customer whose data you want.
x-api-key	yes	string	header	Your API key, which you can find in Settings > API.

Proper query format

The correct API query using customer ID 12 should be: https://client.ecdp.app/customers/id/{12}

Response codes

200: Success

The query was processed, the server returned a response.

Sample response:

{
  "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

Your request was missing an API key, or you don’t have permission to access this information.

Sample response:

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

404: Not found

The data you’re looking for isn’t on the server.

Sample response:

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

GET{email} method using the customer email

This method gets customer information using their email address.

Endpoint#

The endpoint for GET{email} requests is: https://api.ecdp.app/customers/email/{email}

Request parameters

Parameter	Required	Type	Used in	Description
email	yes	string	URL path	The customer’s email address.
x-api-key	yes	string	header	Your API key, which you can find in Settings > API.

Proper query format

The correct API query using the following customer email adam@email.com is as follows: https://client.ecdp.app/customers/email/{adam@email.com}

Response codes

200: Success

Your request was processed, and the server returned a response.

Sample response:

{
  "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

Your request was missing an API key, or you don’t have permission to access this information.

Sample response:

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

404: Not found

The data you’re looking for isn’t on the server.

Sample response:

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

GET{phone} method using the customer phone

This method gets customer information using their phone number.

Endpoint

The endpoint for GET{phone} requests is: https://api.ecdp.app/customers/phone/{phone}

Request parameters

Parameter	Required	Type	Used in	Description
phone	yes	string	URL path	The customer’s phone number.
x-api-key	yes	string	header	Your API key, which you can find in Settings > API.

Proper query format

The correct API query using customer phone number 123 456 789 looks like this:

https://client.ecdp.app/customers/phone/{123456789}

Response codes

200: Success

Your request was processed, and the server returned a response.

Sample response:

{
  "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

Your request was missing an API key, or you don’t have permission to access this information.

Sample response:

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

404: Not found

The data you’re looking for isn’t on the server.

Sample response:

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

GET{crmId} method using the customer CRM ID

This method gets customer information using their CRM ID number.

Endpoint

The endpoint for GET{crmId} requests is: https://api.ecdp.app/customers/crmId/{crmId}

Request parameters

Parameter	Required	Type	Used in	Description
crmID	yes	string	URL path	The customer’s CRM number.
x-api-key	yes	string	header	Your API key, which you can find in Settings > API.

Proper query format

The correct API query using a customer CRM ID 20 looks like this:

https://client.ecdp.app/customers/phone/{20}

Response codes

200: Success

Your request was processed, and the server returned a response.

Sample response:

{
  "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

Your request was missing an API key or you don’t have permission to access this information.

Sample response:

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

404: Not found

The data you’re looking for isn’t on the server.

Sample response:

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

Customers – API methods

POST method – adding customer information

Endpoint

Request parameters

Custom attribute parameters

Consent data parameters

Consents parameters

Request body

Response codes

GET method – getting customer information

GET{id} method using customer ID

Endpoint

Request parameters

Proper query format

Response codes

GET{email} method using the customer email

Endpoint#

Request parameters

Proper query format

Response codes

GET{phone} method using the customer phone

Endpoint

Request parameters

Proper query format

Response codes

GET{crmId} method using the customer CRM ID

Endpoint

Request parameters

Proper query format

Response codes