Customers – API methods
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"
}