API Sign Up Form

Although we provide code for an integrated online sign up form (capturing name, email and assigning a contact preference), there may be times where you want to collect additional data.

This could be applying a tag to the customers using the form to power a ticket ballot, to record where the sign up originated from or just adding additional contact preferences.

Bot management

Spektrix maintains a bot management solution to prevent spam sign up attacks to the /customer endpoint. We would still encourage you to explore additional methods such as Honeypot traps and/or a Recaptcha solution to help discourage any attempts to attack this endpoint.

The below walks through some examples of the information you may want to add to a clients system via a custom sign up form.

When adding any customer data to Spektrix, we always require firstname, lastname and email address. From there you can add any combination of the examples below. For a full list of all available options, please refer to this API endpoint page

Client side vs Server side calls

Creating a customer record

It is possible to create a new customer record in Web mode or System Owner mode. In Web mode, API requests must be made client side. In System Owner mode API requests must be made server side.

Mode	Server or client	API request	Authentication
Web	Client	POST `api/v3/customer`	None
System Owner	Server	POST `api/v3/customers`	Authorization header

Using api/v3/customer server side

In the past, it has been possible to create Customer records server side using Web mode API calls (api/v3/customer). However, due to updated security policies, these requests are likely to be automatically blocked: to avoid this, server side requests to create Customer records should be made in Owner mode (api/v3/customers). If you are creating Customer records server side in Web mode and changing this behavior is a problem, please get in touch with us via support@spektrix.com to discuss options.

Updating a customer record

It is also possible to update a customer record. The process involves looking up an existing record and then amending it.

This is only possible for API requests made server side in System Owner mode, unless you have a logged-in customer, which is an unlikely user flow when they are using an API sign-up form.

Mode	Server or client	API request	Authentication
Web	Client	PATCH `api/v3/customer`	Customer login
System Owner	Server	PATCH `api/v3/customers/{customerId}`	Authorization header

Obtaining Authorisation

For System Owner Mode, Spektrix clients are able to give you authorised access to the API on their system to access confidential data. They will send you credentials consisting of a username and key. These can be used following the instructions here to construct your request header and will then allow you to make the following calls.

Creating a customer record

To add customer details to a system, we can use the customer endpoint for client side API requests in web mode. The below sequence can be completed without authorisation, but it is also possible to do in system owner mode for server side requests.

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.

Request
Body
Response

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

{
	"email": "email@domain.com",
	"firstName": "Users First Name",
	"lastName": "Users Last Name"
}

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

Adding Contact Preferences

When adding a customer to the system via the API, they will not be assigned any contact preferences as default.

To find available preferences:

Request
Response

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

[
	{
		"id": "Unique Preference ID",
		"text": "Preference Example 1",
		"agreed": null
	},
	{
		"id": "Unique Preference ID",
		"text": "Preference Example 2",
		"agreed": null
	}
]

Then add at the same time as creating a new customer:

Request
Body
Response

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

{
	"email": "email@domain.com",
	"firstName": "Users First Name",
	"lastName": "Users Last Name",
	"AgreedStatements": ["Unique Preference ID"]
}

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

Adding Tags

You may also want to add a tag to the customer record you create.

To find available tags:

Request
Response

GET
https://system.spektrix.com/{{clientname}}/api/v3/tag-groups

[
	{
		"id": "Unique Tag Group ID",
		"name": "Spektrix Testing",
		"description": "",
		"tags": [
			{
				"id": "Unique Tag ID",
				"name": "Ballot Tag Example"
			},
			{
				"id": "Unique Tag ID",
				"name": "Sign Up Tag Example"
			}
		]
	}
]

Then add at the same time as creating a new customer:

Request
Body

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

json

{
	"email": "email@domain.com",
	"firstName": "Users First Name",
	"lastName": "Users Last Name",
	"Tags": ["Unique Tag ID", "Unique Tag ID"]
}
</TabItem>
<TabItem value="Response" label="Response">
```json
{
	"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
}

Adding Attributes

The client you are working with may have some custom Attribute values that they would like assigning to the new customer record.

Attributes

Attribute names must be sent across to Spektrix in the format they appear in a clients system, including any Spaces the text may contain. Once added we return the completed attribute name/value pair, but we concatenate the value and output back in Pascal Case. Please check with the client how the attribute appears in there settings interface.

Attributes can be added first using the Attribute_ declaration, then the name of the attribute as it appears in the clients system and required value.

Request
Body
Response

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

{
	"email": "email@domain.com",
	"firstName": "Users First Name",
	"lastName": "Users Last Name",
	"attribute_Example Attribute": "My Attribute Value",
	"attribute_lowercase pascal example": "My Attribute Value"
}

{
	"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_ExampleAttribute": "My Attribute Value",
	"attribute_LowercasePascalExample": "My Attribute Value"
}

Date of Birth

It's also possible to capture Date of Birth if required by your client.

Request
Body
Response

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

{
	"email": "email@domain.com",
	"firstName": "Users First Name",
	"lastName": "Users Last Name",
	"BirthDate": "YYYY/MM/DD"
}

{
	"age": Calculated Integer Value,
	"billingAddress": null,
	"deliveryAddress": null,
	"birthDate": "YYYY-MM-DDT00:00:00",
	"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
}

Duplicates

With any of the above calls, if a customer record already exists inside the clients system you will receive the following 400 error.

{
	"resourceType": "Customer",
	"resourceIdentifiers": ["email@domain.com"],
	"errorCode": 3,
	"message": "Duplicate Entry"
}

If you do wish to add information to an existing record, first you must obtain authorisation on the desired system.

Updating a customer record

Once having authorised access to access customer records you then need to find the unique customer ID associated with the email address you wish to update. You can query the system using a customers email address.

Request
Response

GET
https://system.spektrix.com/{{clientname}}/api/v3/customers?email={{email}}

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

Once you have the Customer ID, you can then add the desired Tag or Contact Preference you need to the record.

Adding a Tag to Existing Record

Request
Body
Response

POST
https://system.spektrix.com/{{clientname}}/api/v3/customers/{{id}}/tags

{
	"id": "Unique Tag ID"
}

{
	"id": "Unique Tag ID",
	"name": "Tag Name"
}

Adding a Contact Preferences to Existing Record

Request
Body
Response

POST
https://system.spektrix.com/{{clientname}}/api/v3/customers/{id}/agreed-statements

[
	{
		"id": "Unique Preference ID"
	}
]

[
  {
    "id": "Unique Preference ID",
    "text": "Preference Name",
    "agreed": true
  }
]

Adding additional information via PATCH

As mentioned above, options such as Date of Birth and Attributes can be added to an existing record via a PATCH. This page on the customers PATCH call provides a full list of options.

Request
Body
Response

PATCH
https://system.spektrix.com/{{clientname}}/api/v3/customers/{id}

{
	"BirthDate": "YYYY/MM/DD",
	"attribute_Example Attribute": "My Attribute Value",
	"attribute_lowercase pascal example": "My Attribute Value"
}

{
	"age": Calculated Integer Value,
	"billingAddress": null,
	"deliveryAddress": null,
	"birthDate": "YYYY-MM-DDT00:00:00",
	"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_ExampleAttribute": "My Attribute Value",
	"attribute_LowercasePascalExample": "My Attribute Value"
}

Client side vs Server side calls​

Creating a customer record​

Updating a customer record​

Obtaining Authorisation​

Creating a customer record​

Adding Contact Preferences​

Adding Tags​

Adding Attributes​

Date of Birth​

Duplicates​

Updating a customer record​

Adding a Tag to Existing Record​

Adding a Contact Preferences to Existing Record​

Adding additional information via PATCH​

Client side vs Server side calls

Creating a customer record

Updating a customer record

Obtaining Authorisation

Creating a customer record

Adding Contact Preferences

Adding Tags

Adding Attributes

Date of Birth

Duplicates

Updating a customer record

Adding a Tag to Existing Record

Adding a Contact Preferences to Existing Record

Adding additional information via PATCH