API Kit Registration

With API kit registration enabled, your members activate kits inside your own product: your activation flow records consent first, then registers the kit, without the test taker ever visiting a SiPhox page.

Enable access for your account

Both endpoints on this page (Kit Consent and Kit Registration) are disabled by default on every token, and calls made before access is granted return 503 Service Unavailable. To enable them:

1. Ask your SiPhox account manager (or support) to enable API kit registration for your business.
2. Say which environments you need. Enablement is per account and may differ between your live and sandbox tokens; if you want to build and test the flow before going live, ask for both explicitly.
3. Build the consent step into your activation UI before the registration call: the required confirmations below must be shown to the test taker, and consent must be recorded successfully before register is called, otherwise registration returns 428 Precondition Required.

Kit Consent API

Record the test taker's consent and identity for a kit. This must be called and succeed before registering the kit via the Kit Registration API: registering a kit with no recorded consent returns 428 Precondition Required.

Send the same customer details as the registration request; they are stored alongside the consent record.

Endpoint

POST /api/v1/kits/{kitID}/consent

Required confirmations

Two confirmations are mandatory and must be sent as true. Your activation interface must present these statements together with accessible links to the Terms of Service and Privacy Policy:

Field	The test taker confirms
isTestTaker	"I am the test taker and confirm that I am the same person registering this kit and taking the test."
hasAcceptedTos	"I have read and accepted the Terms of Service and Privacy Policy."

New York State

New York is an either/or gate: the request must include at least one of notNYResident: true or investigationalUseConsent: true.

• A test taker outside New York sends notNYResident: true.
• A New York resident sends notNYResident: false together with investigationalUseConsent: true, after your activation interface shows the investigational-use disclaimer and collects that consent separately.

The consent value is stored on the consent record and carried into the report consent. If neither field is true, the API returns 400 with: "You must confirm you are not a resident of New York State, or consent to the investigational use of this test."

Path Parameters

Parameter	Type	Required	Description
kitID	string	Yes	The kit ID the consent applies to

Request Body

Field	Type	Required	Description
isTestTaker	boolean	Yes	Must be true (see confirmations above)
hasAcceptedTos	boolean	Yes	Must be true (see confirmations above)
notNYResident	boolean	No	Defaults to false. See the New York State gate above
investigationalUseConsent	boolean	No	Defaults to false. Required as true when notNYResident is false
firstName	string	Yes	Test taker's first name
lastName	string	Yes	Test taker's last name
email	string	Yes	Test taker's email address
dateOfBirth	string	Yes	Date of birth (YYYY-MM-DD)
sex	string (M/F)	Yes	Biological sex
phone	string	No	Phone number
addressLine1	string	No	Street address line 1
addressLine2	string	No	Street address line 2
city	string	No	City
state	string	No	State
zip	string	No	ZIP / postal code
country	string	No	Country
race	string[]	No	Optional race/ethnicity identifiers
consentForResearch	boolean	No	Whether the test taker consents to research use of their data (default false)

Example Request

POST /api/v1/kits/SPOT6WTLQH/consent
Authorization: Token YOUR_API_TOKEN
Content-Type: application/json

{
  "isTestTaker": true,
  "notNYResident": true,
  "hasAcceptedTos": true,
  "consentForResearch": false,
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "dateOfBirth": "1990-01-15",
  "sex": "M",
  "phone": "+15551234567",
  "addressLine1": "123 Main St",
  "city": "Boston",
  "state": "MA",
  "zip": "02101",
  "country": "US"
}

Example Response (200)

{
  "message": "Consent recorded",
  "kitID": "SPOT6WTLQH"
}

Error Responses

Status	Error	Description
400	Validation failed	A required confirmation is missing/not true, or a required customer field is missing. The details array names what failed.
404	KIT_NOT_FOUND	Kit not found or does not belong to this business
503	NOT_AVAILABLE	Kit registration is not enabled for this account

Kit Registration API

Register a kit to a customer by kit ID. If the customer (identified by email) does not already exist, one is created automatically.

Registration triggers asynchronous lab processing. The response confirms that registration has been initiated, not that it is complete.

⚠️ Consent is required first. You must record the test taker's consent for the kit via the Kit Consent API and receive a successful response before calling this endpoint. Registering a kit with no recorded consent returns 428 Precondition Required.

Status: Access to this endpoint is granted on request. Contact your SiPhox account manager to enable it for your API key. Calls made before access is granted return 503 Service Unavailable.

Endpoint

POST /api/v1/kits/{kitID}/register

Path Parameters

Parameter	Type	Required	Description
kitID	string	Yes	The kit ID to register

Request Body

Field	Type	Required	Description
firstName	string	Yes	Customer's first name
lastName	string	Yes	Customer's last name
email	string	Yes	Customer's email address
dateOfBirth	string	Yes	Date of birth (YYYY-MM-DD)
sex	string (M/F)	Yes	Biological sex
phone	string	No	Phone number (required for EasyDraw kits to receive SMS instructions)
addressLine1	string	No	Street address line 1
addressLine2	string	No	Street address line 2
city	string	No	City
state	string	No	State
zip	string	No	ZIP / postal code
country	string	No	Country
race	string[]	No	Optional race/ethnicity identifiers
consentForResearch	boolean	No	Whether the customer consents to research use of their data (default false)

Example Request

POST /api/v1/kits/SPOT6WTLQH/register
Authorization: Token YOUR_API_TOKEN
Content-Type: application/json

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "dateOfBirth": "1990-01-15",
  "sex": "M",
  "phone": "+15551234567",
  "addressLine1": "123 Main St",
  "city": "Boston",
  "state": "MA",
  "zip": "02101",
  "country": "US",
  "consentForResearch": true
}

Example Response (200)

{
  "message": "Kit registration initiated",
  "kitID": "SPOT6WTLQH",
  "customerId": "64fa1df97cf8d322cfa492eb"
}

Error Responses

Status	Error	Description
400	Validation failed	The request body failed validation
404	KIT_NOT_FOUND	Kit not found or does not belong to this business
409	KIT_ALREADY_REGISTERED	The kit has already been registered
428	CONSENT_REQUIRED	No consent was recorded for this kit; call the Kit Consent API first
503	NOT_AVAILABLE	Kit registration is not enabled for this account

Notes

• Consent must be recorded for the kit before registration. See the Kit Consent API.
• Kit registration is processed asynchronously. After a successful 200 response, lab processing begins in the background.
• If the email matches an existing customer, the kit is registered to that customer. Missing profile fields (name, date of birth, sex, phone) are filled in from the request.
• If no customer exists with the given email, a new customer account is created automatically.
• For EasyDraw kit types, an SMS with collection instructions is sent to the customer's phone number if provided.