# Customer API
Integrate your existing platforms with the Tallymarks Customer API to make your customer information available for the assessment of customer events.
Also see [Swagger based Customer API documentation](https://api-customer.tallymarks.net/swagger/index.html)
## Get a Customer
Get a Customers details including their email address and contact phone.
### **GET**
```
/api/v1/customers/{customerId}
```
#### Request (Route)
| Element | Type | Description |
| ---------- | --------- | ------------------------------------ |
| customerId | guid/uuid | A unique identifier for the customer |
```
No request body
```
#### Response: 200
| Element | Type | Description |
| ------------------ | --------- | ---------------------------------------------------------------------------------------------------------------- |
| customerId | guid/uuid | A unique identifier for the customer |
| tenantId | guid/uuid | A unique identifier for the tenant |
| firstName | string | First Name |
| lastName | string | Last Name |
| displayName | string | Display Name |
| emailAddress | string | Email Address |
| isAccountLocked | bool | A flag indicated that the account is locked (if true) |
| mobileNumber | string | A customer mobile number |
| optinSms | bool | Flags that the Customer has been opted in for Sms |
| optinEmail | bool | Flags that the Customer has been opted in for Email |
| acceptTerms | bool | Flags that the Customer has been accepted program terms and conditions |
| attributes\[] | array | A list of attributes |
| attributes\[]key | string | Attribute Key |
| attributes\[]value | string | Attribute Value |
| dateOfBirth | datetime | Date of Birth |
| createdAt | datetime | The customer creation date/time.
This also represents the Customers Anniversary Date
|
| changedAt | datetime | The last date/time the customer entity was modified |
| contactPhone | string | Contact Phone Number |
| externalReference | string | An external reference for the customer |
| externalStatus | string | An external status for the customer, for example "active", "delinquent" |
```
{
"customerId": "string",
"tenantId": "string",
"firstName": "string",
"lastName": "string",
"displayName": "string",
"emailAddress": "string",
"isAccountLocked": true,
"mobileNumber": "string",
"optinSms": true,
"optinEmail": true,
"acceptTerms": true
"attributes": [
{
"name": "string",
"value": "string"
}
],
"dateOfBirth": "2020-02-29T03:36:19.448Z",
"createdAt": "2020-02-29T03:35:23.929Z",
"changedAt": "2020-02-29T03:35:23.929Z",
"contactPhone": "string",
"externalReference": "string",
"externalStatus": "string"
}
```
## Update a Customer
This method allows customers to be updated in the TallyMarks system on an individual basis. Email address must be unique to each TallyMarks Account.
### PATCH
```
/api/v1/customers/{customerId}
```
#### Request
| Element | Type | Description |
| ------------------ | --------- | ----------------------------------------------------------------------- |
| customerId | guid/uuid | A unique identifier for the customer |
| tenantId | guid/uuid | A unique identifier for the tenant |
| firstName | string | First Name |
| lastName | string | Last Name |
| displayName | string | Display Name |
| emailAddress | string | emailAddress |
| isAccountLocked | bool | A flag indicated that the account is locked (if true) |
| mobileNumber | string | A customer mobile number |
| optinSms | bool | Flags that the Customer has been opted in for Sms |
| optinEmail | bool | Flags that the Customer has been opted in for Email |
| acceptTerms | bool | Flags that the Customer has been accepted program terms and conditions |
| attributes\[] | Array | A list of attributes |
| attributes\[]key | string | Attribute Key |
| attributes\[]value | string | Attribute Value |
| dateOfBirth | datetime | Date of Birth |
| contactPhone | string | Contact Phone Number |
| externalReference | string | An external reference for the customer |
| externalStatus | string | An external status for the customer, for example "active", "delinquent" |
```
{
"customerId": "string",
"firstName": "string",
"lastName": "string",
"displayName": "string",
"emailAddress": "string",
"mobileNumber": "string",
"optinSms": true,
"optinEmail": true,
"acceptTerms": true
"dateOfBirth": "2020-02-29T03:36:19.448Z",
"attributes": [
{
"name": "string",
"value": "string"
}
],
"contactPhone": "string",
"externalReference": "string",
"externalStatus": "string"
}
```
#### Response: 200 - Customer Updated
#### Response: 400 - Email Aleady Exists
#### Response: 400 - Customer Not Found
## Search for Customers
Support the searching of customers.
### GET
```
/api/v1/customers
```
#### Request (Query String)
| Element | Type | Description |
| --------- | ------- | ----------------------------------------------------- |
| keyword | decimal | Represents an amount related to the action |
| limit | integer | A unique identifier for the event |
| offsetKey | string | A unique identifier for the next set of paged results |
```
No Body
```
#### Response: 200
| Event | Type | Description |
| ------------------------------ | --------- | ----------------------------------------------------------------------- |
| customers\[] | array | Array of customer results |
| customers\[].customerId | guid/uuid | A unique identifier for the customer |
| customers\[].tenantId | guid/uuid | A unique identifier for the tenant |
| customers\[].firstName | string | First Name |
| customers\[].lastName | string | Last Name |
| customers\[].displayName | string | Display Name |
| customers\[].emailAddress | string | emailAddress |
| customers\[].contactPhone | string | Contact Phone Number |
| customers\[].externalReference | string | An external reference for the customer |
| customers\[].externalStatus | string | An external status for the customer, for example "active", "delinquent" |
| offsetKey | string | key for next page of results |
```
{
"customers": [
{
"customerId": "string",
"tenantId": "string",
"firstName": "string",
"lastName": "string",
"displayName": "string",
"emailAddress": "string",
"createdAt": "2020-02-29T03:39:39.010Z",
"changedAt": "2020-02-29T03:39:39.010Z",
"contactPhone": "string",
"externalReference": "string",
"externalStatus": "string"
}
],
"offsetKey": "string"
}
```
## Create Customer
This method allows customers to be created in the TallyMarks system on an individual basis. Once created a customer can receive events for assessment and fufilment. Email address must be unique to each TallyMarks Account.
### POST
```
/api/v1/events/redemptions
```
#### Request
| Element | Type | Description |
| ------------------ | --------- | ----------------------------------------------------------------------- |
| customerId | guid/uuid | A unique identifier for the customer |
| firstName | string | First Name |
| lastName | string | Last Name |
| displayName | string | Display Name |
| emailAddress | string | emailAddress |
| mobileNumber | string | A customer mobile number |
| optinSms | bool | Flags that the Customer has been opted in for Sms |
| optinEmail | bool | Flags that the Customer has been opted in for Email |
| acceptTerms | bool | Flags that the Customer has been accepted program terms and conditions |
| attributes\[] | Array | A list of attributes |
| attributes\[]key | string | Attribute Key |
| attributes\[]value | string | Attribute Value |
| dateOfBirth | datetime | Date of Birth |
| contactPhone | string | Contact Phone Number |
| externalReference | string | An external reference for the customer |
| externalStatus | string | An external status for the customer, for example "active", "delinquent" |
```
{
"customerId": "string",
"firstName": "string",
"lastName": "string",
"displayName": "string",
"emailAddress": "string",
"mobileNumber": "string",
"optinSms": true,
"optinEmail": true,
"acceptTerms": true
"dateOfBirth": "2020-02-29T03:41:46.155Z",
"attributes": [
{
"name": "string",
"value": "string"
}
],
"contactPhone": "string"
"externalStatus": "string",
"externalReference": "string"
}
```
#### Response: 200 - Customer Registered
| Element | Type | Description |
| ------------------ | --------- | ---------------------------------------------------------------------------------------------------------------- |
| customerId | guid/uuid | A unique identifier for the customer |
| firstName | string | First Name |
| lastName | string | Last Name |
| displayName | string | Display Name |
| emailAddress | string | emailAddress |
| isAccountLocked | bool | A flag indicated that the account is locked (if true) |
| mobileNumber | string | A customer mobile number |
| optinSms | bool | Flags that the Customer has been opted in for Sms |
| optinEmail | bool | Flags that the Customer has been opted in for Email |
| acceptTerms | bool | Flags that the Customer has been accepted program terms and conditions |
| attributes\[] | Array | A list of attributes |
| attributes\[]key | string | Attribute Key |
| attributes\[]value | string | Attribute Value |
| dateOfBirth | datetime | Date of Birth |
| createdAt | datetime | The customer creation date/time.
This also represents the Customers Anniversary Date
|
| changedAt | datetime | The last date/time the customer entity was modified |
| contactPhone | string | Contact Phone Number |
| externalReference | string | An external reference for the customer |
| externalStatus | string | An external status for the customer, for example "active", "delinquent" |
```
{
"customerId": "string",
"tenantId": "string",
"firstName": "string",
"lastName": "string",
"displayName": "string",
"emailAddress": "string",
"isAccountLocked": bool,
"mobileNumber": "string",
"optinSms": true,
"optinEmail": true,
"acceptTerms": true
"attributes": [
{
"name": "string",
"value": "string"
}
],
"createdAt": "2020-02-29T03:41:46.188Z",
"changedAt": "2020-02-29T03:41:46.188Z",
"contactPhone": "string",
"externalReference": "string",
"externalStatus": "string"
}
```
#### Response: 400 - Email Already Registered
## Get a Customer's Points Balance
This method supports the retrieval of the customers current points balance.
### GET
```
/api/v1/customers/{customerId}/balance
```
#### Request (Route Parameter)
| Element | Type | Description |
| ---------- | --------- | ------------------------------------ |
| customerId | guid/uuid | A unique identifier for the customer |
```
No Body
```
#### Response: 200
| Event | Type | Description |
| ------------- | --------- | ------------------------------------------------------------ |
| tenantId | guid/uuid | A unique identifier for the tenant |
| customerId | guid/uuid | A unique identifier for the customer |
| tenantId | guid/uuid | |
| pointsSegment | string | A points segment, currently "base" (reserved for future use) |
| amount | int | Points Balance |
| changedAt | datetime | Last date/time the Points Balance was updated. |
```
{
"tenantId": "string",
"customerId": "string",
"pointsSegment": "string",
"amount": 0,
"changedAt": "2020-02-29T04:59:49.764Z"
}
```
## Search for a Customer's Events
This method supports the searching of events relating to a customer. Results are paged, with a maximum (limit) of 100 records.
### GET
```
/api/v1/customers/events
```
#### Request (Query String)
| Element | Type | Description |
| ---------- | --------- | --------------------------------------------------------------------------------- |
| customerId | guid/uuid | A unique identifier for the customer |
| eventId | uid/uuid | A unique identifier for the event |
| eventType | string | An event type: action, order, transaction, redemption, points, error, anniversary |
| keyword | string | Keyword search of event namespace or reference |
| fromAt | datetime | Event date/time (from) |
| toAt | datetime | Event date/time (to) |
```
No Body
```
#### Response: 200
| Event | Type | Description |
| -------------------- | --------- | --------------------------------------------------------------------------------- |
| events\[] | array | Array of events results |
| events\[].eventId | guid/uuid | A unique identifier for the event |
| events\[].tenantId | guid/uuid | A unique identifier for the tenant |
| events\[].customerId | guid/uuid | A unique identifier for the customer |
| events\[].createdAt | string | Date/Time the event was created. |
| events\[].eventType | string | An event type: action, order, transaction, redemption, points, error, anniversary |
| events\[].nameSpace | string | NameSpace of event |
| events\[].reference | string | Reference |
| | | |
```
{
"events": [
{
"eventId": "string",
"tenantId": "string",
"customerId": "string",
"createdAt": "2020-02-29T05:02:15.324Z",
"eventType": "string",
"nameSpace": "string",
"reference": "string"
}
],
"offsetKey": "string"
}
```
## Search for a Customer's Transactions
This method supports the searching of points transactions relating to a customer’s in response to the assessment of their events. Results are paged, with a maximum (limit) of 100 records.
### GET
```
/api/v1/customers/transactions
```
#### Request (Query String)
| Element | Type | Description |
| ---------- | --------- | --------------------------------------------------------------------------------- |
| customerId | guid/uuid | A unique identifier for the customer |
| eventId | uid/uuid | A unique identifier for the event |
| eventType | string | An event type: action, order, transaction, redemption, points, error, anniversary |
| keyword | string | Keyword search of event namespace or reference |
| fromAt | datetime | Event date/time (from) |
| toAt | datetime | Event date/time (to) |
| limit | int | limit number of results |
| offsetKey | string | key for next page of results |
```
No Body
```
#### Response: 200
| Event | Type | Description |
| ----------------------------------------- | --------- | -------------------------------------------------------------------------------------- |
| customerTransactions\[] | array | Array of Customer Transactions |
| customerTransactions\[].transactionId | guid/uuid | A unique identifier for the event |
| customerTransactions\[].eventId | guid/uuid | A unique identifier for the event |
| customerTransactions\[].tenantId | guid/uuid | A unique identifier for the tenant |
| customerTransactions\[].customerId | guid/uuid | A unique identifier for the customer |
| customerTransactions\[].assessmentRuleId | guid/uuid | A unique identifier for the assessment rule that was matched to create the transaction |
| customerTransactions\[].createdAt | string | Date/Time the event was created. |
| customerTransactions\[].checkSum | string | A unique identifier for the transaction |
| customerTransactions\[].nameSpace | string | NameSpace of event |
| customerTransactions\[].description | string | Description of the event |
| customerTransactions\[].amount | int | Points Transaction |
| customerTransactions\[].externalReference | string | Reference |
| | | |
```
{
"customerTransactions": [
{
"transactionId": "string",
"customerId": "string",
"tenantId": "string",
"eventId": "string",
"assessmentRuleId": "string",
"createdAt": "2020-02-29T05:08:52.159Z",
"checkSum": "string",
"nameSpace": "string",
"description": "string",
"amount": 0,
"externalReference": "string"
}
],
"offsetKey": "string"
}
```
## Search for Customer's Segments
This method supports the retrieval of all lists that a customer is a member of.
### GET
```
/api/v1/customers/{customerId}/segments
```
#### Request (Query String)
| Element | Type | Description |
| --------- | ------- | ---------------------------- |
| limit | integer | limit number of results |
| offsetKey | string | key for next page of results |
```
No Body
```
#### Response: 200
| Event | Type | Description |
| -------------------------- | --------- | --------------------------------------------------------------------------------- |
| segments\[] | array | Array of segments |
| segments\[].tenantId | guid/uuid | A unique identifier for the tenant |
| segments\[].name | string | Name of Segment |
| segments\[].description | string | Description of Segment |
| segments\[].displayName | string | Display Name |
| segments\[].createdAt | datetime | Date/time customer was assigned to segment |
| segments\[].changedAt | datetime | Date/time customer configuration related to segment was updated |
| segments\[].sourceEventId | guid/uuid | The Event Id that resulted in the Customer being assigned to the segment |
| segments\[].expiryDateTime | datetime | Date/time that the customer's membership of the segment will automatically expire |
| offsetKey | string | key for next page of results |
```
{
"segments": [
{
"segmentId": "string",
"tenantId": "string",
"name": "string",
"description": "string",
"createdAt": "2020-02-29T05:14:21.361Z",
"changedAt": "2020-02-29T05:14:21.361Z",
"sourceEventId": "string",
"expiryDateTime": "2020-02-29T05:14:21.361Z"
}
],
"offsetKey": "string"
}
```
## Add Customer to Segment
This method supports the retrieval of all lists that a customer is a member of.
### PUT
```
/api/v1/customers/{customerId}/segments
```
#### Request (Body)
| Element | Type | Description |
| --------- | --------- | ----------------------------------- |
| segmentId | guid/uuid | A unique identifier for the segment |
```
{
"segmentId": "string"
}
```
#### Response: 200
| Event | Type | Description |
| -------------- | --------- | --------------------------------------------------------------------------------- |
| tenantId | guid/uuid | A unique identifier for the tenant |
| segmentId | guid/uuid | A unique identifier for the segment |
| name | string | Name of Segment |
| description | string | Description of Segment |
| displayName | string | Display Name |
| createdAt | datetime | Date/time customer was assigned to segment |
| changedAt | datetime | Date/time customer configuration related to segment was updated |
| sourceEventId | guid/uuid | The Event Id that resulted in the Customer being assigned to the segment |
| expiryDateTime | datetime | Date/time that the customer's membership of the segment will automatically expire |
```
{
"segmentId": "string",
"tenantId": "string",
"name": "string",
"description": "string",
"createdAt": "2020-02-29T05:14:21.361Z",
"changedAt": "2020-02-29T05:14:21.361Z",
"sourceEventId": "string",
"expiryDateTime": "2020-02-29T05:14:21.361Z"
}
```
## Delete Customer from Segment
This method supports the retrieval of all lists that a customer is a member of.
### DELETE
```
/api/v1/customers/{customerId}/segments/{segmentId}
```
#### Request (Query String)
None
#### Response: 200