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 | 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 |
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 |
Consent data parameters
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 |
Consents parameters
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 |
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"
}