Register Users

Register a user in the Distinct system via the user registration endpoint.

Endpoint

POST https://api.distinct.so/v2/registration

Request Headers

Key	Value
Content-Type	application/json
x-distinct-api-key	Your shared API key

Request Body

Key	Type	Required	Description
firstName	String	Yes	First name of the user
lastName	String	No	Last name of the user
email	String	Yes	Email address of the user
isTermsAndConditionsChecked	Boolean	Yes	Indicates if the user agreed to the TOS and Privacy Policy
subscribeNewsletter	Boolean	Yes	Indicates if the user opted in to receive promotional emails
phoneNumber	String	No	Unformatted phone number without country code
phoneCountryCode	String	No	Phone number country code (e.g. "+1")
phoneCountryName	String	No	Phone number country name (e.g. "us")
birthYear	Number	Yes	Birth year of the user
birthMonth	Number	Yes	Birth month of the user
birthDate	Number	Yes	Birth day of the user
dob	ISOTimestamp	Yes	Full date of birth in ISO date/time format
experienceValue	String	Yes	Unique experience identifier mapping the user to an experience
registrationPageValue	String	Yes	Unique registration page identifier mapping the user to a registration page
language	String	Yes	Language preference (e.g. "en-IE")
externalVendorId	String	Yes	External mapping ID (e.g. for Vendor campaignId: "mkod0a8imkod0a")

info

• Optional fields should be omitted from the request body if there are no values — do not send them as empty strings or null.
• When a phone number is available, include all phone fields (phoneNumber, phoneCountryCode, phoneCountryName).
• If externalVendorId is sent, registrationPageValue must be set to "external-vendor-registration".

Response

Success (200)

{
  "statusCode": 200,
  "message": "Registration successful.",
  "data": {}
}

Example Request

cURL

curl -X POST 'https://api.distinct.so/v2/registration' \
-H 'Content-Type: application/json' \
-H 'x-distinct-api-key: <shared-api-key>' \
-d '{
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@example.com",
"isTermsAndConditionsChecked": true,
"subscribeNewsletter": false,
"phoneNumber": "5555555555",
"phoneCountryCode": "+1",
"phoneCountryName": "us",
"dob": "1990-05-15T00:00:00Z",
"experienceValue": "wc-trophy-tour-2026",
"registrationPageValue": "external-vendor-registration",
"language": "en-IE",
"externalVendorId": "mkod0a8imkod0a"
}'

Replace the placeholders:

• <shared-api-key> — your actual shared API key from Distinct

tip

The birthDate and birthMonth fields do not require leading zeros. If you do not have a newsletter/promotional email opt-in, set subscribeNewsletter to false.

Response Structure

Status Code	Description	Example Response
200	User registered successfully	{"statusCode": 200, "message": "User created successfully", "data": true}
400	Phone number already exists	{"statusCode": 400, "message": "User phone number already registered", "data": {}}
400	Missing external vendor ID (only when registrationPageValue is "external-vendor-registration")	{"statusCode": 400, "message": "External vendor id is required", "data": {}}
400	Registration page not found (when externalVendorId is sent but no registration page matches)	{"statusCode": 400, "message": "Registration page not found", "data": {}}
500	Internal server error	{"statusCode": 500, "message": "Event is not active, Please report this issue to the support team.", "data": {}}

Notes

1. The x-distinct-api-key will be shared with you by the Distinct team and must be included in every API request.
2. The request body must be sent as application/json with all required fields.
3. Optional fields should be omitted from the payload if there are no values.
4. When a phone number value is available, include all phone fields (phoneNumber, phoneCountryCode, phoneCountryName).
5. If externalVendorId is to be sent, the value for registrationPageValue must be "external-vendor-registration".
6. Optional IP allowlisting — You can share a list of IP addresses with the Distinct team to be whitelisted against your API key for an additional layer of security. When configured, requests from any other IP are rejected with 403.