Skip to main content

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.

ModeServer or clientAPI requestAuthentication
WebClientPOST api/v3/customerNone
System OwnerServerPOST api/v3/customersAuthorization 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.

ModeServer or clientAPI requestAuthentication
WebClientPATCH api/v3/customerCustomer login
System OwnerServerPATCH 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.

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

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:

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

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

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

Adding Tags

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

To find available tags:

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

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

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

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.

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

Date of Birth

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

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

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.

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

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

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

Adding a Contact Preferences to Existing Record

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

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.

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