Register a Donor | Documentation for the Hill Labs API

Description

Use this endpoint to register donor details. Then include the same identifier in an order so the anonymised donor details can appear on results.

This endpoint is specialised for drug testing. If you want to use it, discuss it with the Customer Experience team.

Endpoint

Testing: POST https://cat-api.hill-laboratories.com/client/api/v3/donors

Production: POST https://api.hill-laboratories.com/client/api/v3/donors

Required Headers

Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

Schema

Testing: CreateDonorRequestSchema.json

Production: CreateDonorRequestSchema.json

Purpose

When you create a donor record with an identifier, name, date of birth and gender, the API returns a donorId. Include the same identifier in your sample payload so Hill Labs can associate the anonymised donor details with that sample on results.

Request Object

Field	Value type	Validation	Description
`identifier`	string	Required. MaxLength = 32	Client-supplied lookup key for the donor (e.g. DO123456). Treat as your unique, case-sensitive lookup key. Cannot be null or blank.
`firstName`	string	Required. MaxLength = 64	Donor given name. Cannot be null or blank.
`lastName`	string	Required. MaxLength = 64	Donor family name / surname. Cannot be null or blank.
`dateOfBirth`	date	Required (yyyy-mm-dd format). MaxLength = 64	Donor’s date of birth in ISO date format yyyy-mm-dd (date only, no time). e.g. 1987-12-01.
`gender`	Enumerated value – allowed values: `UNKNOWN` `MALE` `FEMALE` `AMBIGUOUS` `NOT_APPLICABLE` `OTHER`	Required	Donor gender. Use one of the enumerated values exactly (case-sensitive).

Example Request

Create Donor Request

{
  "identifier": "DO6543212",
  "firstName": "John",
  "lastName": "Smith",
  "dateOfBirth": "1987-01-01",
  "gender": "MALE"
}

Example Response

Response

{
  "donorId": "123e4567-e89b-12d3-a456-426614174000"
}

Possible Responses

Code	Description	When
201	201 Created	Donor data created ok and donorId returned.
400	400 Bad Request	Incorrect request. Includes a description of the problem
401	401 Unauthorized	An invalid/expired authentication token was supplied
500	500 Internal Server Error	An error occurred on the server while registering a donor