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 three ways:

via the the LoginLogout Iframe
using the v3/customer/authenticate endpoint where the customer logs in with their password
using the passwordless login (magic link) endpoint

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"
}

As an alternative to email/password login, customers can be logged in via a "magic link" - a one-time link emailed to the customer which logs them straight into their account, with no password required.

The flow has two steps:

Your site calls v3/customer/send-magic-link with the customer's email address and a linkUrl on your own website. Spektrix emails the customer a link built from linkUrl.
When the customer clicks that link, the page it opens on your site reads the token out of the URL and calls v3/customer/authenticate-magic-link with it to complete login.

Request
Body
Response

POST
https://system.spektrix.com/{{clientname}}/api/v3/customer/send-magic-link

{
	"emailAddress": "email@domain.com",
	"linkUrl": "https://www.mywebsite.com/account/magic-login?token={token}"
}

{}

linkUrl must be an absolute HTTPS url containing a literal {token} placeholder (replaced by Spektrix with the one-time token before emailing it to the customer), with a host matching a domain already configured for your Spektrix system (the same website domain configuration used elsewhere for your account, e.g. login/my account/checkout links).

The linkUrl page

This page is entirely your own - on load, it should read the token from its URL, call authenticate-magic-link with it, and treat a successful response like a normal authenticate response. On failure (401), ask the customer to request a new link, as tokens are single-use and expire after 10 minutes.

info

To avoid revealing whether an email address is registered, this endpoint returns a success response even if no matching customer is found, and no email is sent in that case.

Request
Body
Response

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

{
	"token": "token from the magic link url"
}

{
	"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"
}

A successful call logs the customer in exactly as v3/customer/authenticate does, setting the same session/cookies and returning the same Customer resource. If a basket was in progress when the magic link was requested, that basket is automatically restored once the customer is logged back in.

tip

Magic link tokens are single-use and expire 10 minutes after being requested. Only one token can be active per customer at a time - requesting a new link invalidates any previously issued, unused token.

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​

Magic Link (Passwordless) Login​

Finding Basic Customer Details​

Using $expand​

Expanding Tags​

Expanding Memberships​

Example Applications​

Streaming and downloadable content​

Digital membership rewards​