API Sign Up Form

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.

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

Adding Basic Customer Details

To add customer details to a system, we can use the customer endpoint. The below sequence can be completed without authorisation.

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.

Obtaining Authorisation

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.

Looking up Customer Records

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
}

Updating Records

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

Adding Basic Customer Details​

Adding Contact Preferences​

Adding Tags​

Adding Attributes​

Date of Birth​

Duplicates​

Obtaining Authorisation​

Looking up Customer Records​

Updating Records​

Adding a Tag to Existing Record​

Adding a Contact Preferences to Existing Record​

Adding additional information via PATCH​