Customer Information

Working with custom domains

In the following article, links will be referenced as originating from system.spektrix.com. If you have implemented a custom domain for your Integration, please replace system.spektrix.com with your chosen subdomain.

There may be times in your integration where you wish to make decisions on customer data that is held in Spektrix. This may be useful for creating pages for Members to see unique content, inform a user of their remaining credit balance, to recommend different products or for richer experiences based on a customer's purchase history.

Using the rich CRM tools in Spektrix, behaviours and actions of customers can be automatically tagged and recorded on a customer record. If a client has set up an automated tagging system in Spektrix, or are using Memberships or Attributes to highlight customers, this information is accessible via the API to be able to make decisions on.

This article looks at how that data can be accessed using client-side calls alongside the customer's log in credentials.

The following calls can all be completed client-side without the need of full system authentication.

Customer Authentication

The first step to find this information is for the customer to log into their online account, thus setting the required browser cookies.

This can be achieved in two ways, by either using the v3/customer/authenticate endpoint, or the LoginLogout Iframe.

Request
Body
Response

POST
https://system.spektrix.com/{{clientname}}/api/v3/customer/authenticate

{
	"email": "email@domain.com",
	"password": "users password"
}

{
	"age": null,
	"billingAddress": null,
	"deliveryAddress": null,
	"birthDate": null,
	"email": "email@domain.com",
	"firstName": "Users First Name",
	"lastName": "Users Last Name",
	"mobile": null,
	"name": "Users First Name Users Last Name",
	"phone": null,
	"title": "",
	"passwordSet": false,
	"giftAidDeclarationRequired": false,
	"id": "Customer ID",
	"creditBalance": value,
	"attribute_name": "attribute_value"
}

Finding Basic Customer Details

Once the user has logged in to their account, you can then retrieve the customers basic details using the below;

Request
Response

GET
https://system.spektrix.com/{{clientname}}/api/v3/customer

{
	"age": null,
	"billingAddress": null,
	"deliveryAddress": null,
	"birthDate": null,
	"email": "email@domain.com",
	"firstName": "Users First Name",
	"lastName": "Users Last Name",
	"mobile": null,
	"name": "Users First Name Users Last Name",
	"phone": null,
	"title": "",
	"passwordSet": false,
	"giftAidDeclarationRequired": false,
	"id": "Customer ID",
	"creditBalance": value,
	"attribute_name": "attribute_value"
}

This will return the basic customer information, including any Attribute values that may have been set on that record.

tip

If using the v3/customer/authenticate method above, this response is the same as when first passing the users details to the system.

Using `$expand`

If we look at the full details of the customer endpoint we can see that some response resources are not found as standard in the basic v3/customer response. These are marked as Collections in the type column.

These collections can be expanded upon by passing an $expand=collectionName parameter onto the v3/customer call to open up that collection in the response.

The below highlights two ways to expand upon Tags and Memberships on a customer record.

tip

It is possible to pass an expand command on the initial authenticate call if required.

Expanding Tags

We can expand a v3/customer call to list the tags (showing the Tag Id and Name) attached to a customer record using $expand=tags;

Request
Response

GET
https://system.spektrix.com/{{clientname}}/api/v3/customer?$expand=tags

{
	"age": null,
	"billingAddress": null,
	"deliveryAddress": null,
	"birthDate": null,
	"email": "email@domain.com",
	"firstName": "Users First Name",
	"lastName": "Users Last Name",
	"mobile": null,
	"name": "Users First Name Users Last Name",
	"phone": null,
	"tags": [
		{
			"id": "unique tag id",
			"name": "Tag Example 1"
		},
		{
			"id": "unique tag id",
			"name": "Tag Example 2"
		}
	],
	"title": "",
	"passwordSet": false,
	"giftAidDeclarationRequired": false,
	"id": "Customer ID",
	"creditBalance": value,
	"attribute_name": "attribute_value"
}

Expanding Memberships

We can expand a v3/customer call to list any memberships attached to a customer record using $expand=subscriptions;

Request
Response

GET
https://system.spektrix.com/{{clientname}}/api/v3/customer?$expand=subscriptions

{
	"age": null,
	"billingAddress": null,
	"deliveryAddress": null,
	"birthDate": null,
	"email": "email@domain.com",
	"firstName": "Users First Name",
	"lastName": "Users Last Name",
	"mobile": null,
	"name": "Users First Name Users Last Name",
	"phone": null,
	"title": "",
	"passwordSet": false,
	"giftAidDeclarationRequired": false,
	"subscriptions": [
		{
			"autoRenew": false,
			"membership": {
				"id": "Unique Membership ID"
			},
			"startDate": "2020-07-01T00:00:00",
			"expiryDate": "2021-06-30T00:00:00",
			"canRenew": false
		},
		{
			"autoRenew": true,
			"membership": {
				"id": "Unique Membership ID"
			},
			"startDate": "2020-04-29T00:00:00",
			"expiryDate": "2021-04-28T00:00:00",
			"canRenew": false
		}
	],
	"id": "Customer ID",
	"creditBalance": value,
	"attribute_name": "attribute_value"
}

The friendly name of the Membership is not returned in the above call. These id's can be matched against Memberships in the system by using v3/memberships;

Request
Response

GET
https://system.spektrix.com/{{clientname}}/api/v3/memberships

[
	{
		"description": "",
		"htmlDescription": "",
		"id": "membershipId",
		"imageUrl": "",
		"name": "Membership Name",
		"thumbnailUrl": ""
	}
]

Example Applications

There are a number of applications for checking customer data using the API, including but not limited to some of the examples below.

Streaming and downloadable content

By setting an auto-tag for customers who have purchased a ticket for a particular event within a certain number of days, you can build a page for on-demand content.

If a user is logged in and has the corresponding tag, you can display the digital content. Other users can be prompted to log in or be redirected to your event listings page to buy a ticket.

Digital membership rewards

You can set up a page like the one detailed above for membership rewards as well. Or, for a more bespoke experience, logged in members could see digital rewards on your membership page, while non-members would see a web component-powered membership purchase screen.

Customer Authentication​

Finding Basic Customer Details​

Using $expand​

Expanding Tags​

Expanding Memberships​

Example Applications​

Streaming and downloadable content​

Digital membership rewards​