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

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