Skip to content

Customers – API methods 

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 RequiredType Used inDescription 
x-api-key yesstring header Your API key, which you can find in Settings > API.
mode yesstring request body Add, Update, AddOrUpdate – choose one action you want to perform.
matchBy yesstring 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 RequiredType Max character countDescription  
emailyesstring 320Customer’s email address – required if email is set as the default matching mode in Settings > Customers.
phoneyesstring 20Customer’s phone number (no spaces) – required if phone is set as the default matching mode in Settings > Customers.
crmIdyesstring 128Customer’s CRM ID number – required if CRM ID is set as the default matching mode in Settings > Customers.
visitorIdnostring38A unique number assigned to every visitor who browses your website.
firstName nostring 256Customer’s first name 
lastName nostring 256Customer’s last name 
dateOfBirth nostring($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 nostring  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 RequiredType Max character countDescription 
name yesstring 256Customer attribute name; a mandatory parameter when you want to add or obtain information about non-standard attributes; minimum number of characters: 1
value nostring Customer attribute value
Parameter RequiredType Description 
consents no Detailed consent data – see Consent parameters.
force noboolean Indicates whether another confirmation link is to be sent for consents marked as “AwaitingConfirmation”, regardless of whether it was sent earlier.
confirmationMessageId nointeger($int32) Confirmation message ID 
Parameter RequiredType Description 
idyesinteger($int32) Single consent ID – required when adding or getting consent information.
value yesstring 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 RequiredType Used inDescription 
idyesstring URL pathThe ID number of the customer whose data you want.
x-api-keyyesstring headerYour 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 RequiredType Used inDescription 
emailyesstring URL pathThe customer’s email address.
x-api-keyyesstring headerYour 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 RequiredType Used inDescription 
phoneyesstring URL pathThe customer’s phone number.
x-api-keyyesstring headerYour 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 RequiredType Used inDescription 
crmIDyesstring URL pathThe customer’s CRM number.
x-api-keyyesstring headerYour 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"
}