Description
Register donor details so orders can reference that donor by identifier and have (anonymised) donor details appear on results.
Endpoint
Testing: POST https://cat-api.hill-laboratories.com/client/api/v3/donors
Production: POST https://api.hill-laboratories.com/client/api/v3/donors
Schema
Testing: https://cat-cdn.hill-laboratories.com/json-schema/client-api/v3/CreateDonorRequestSchema.json
Production: https://cdn.hill-laboratories.com/json-schema/client-api/v3/CreateDonorRequestSchema.json
Purpose
Create a donor record (identifier + name/date-of-birth/gender) and return a donorId. Once created, you can place the same identifier into sample payloads (see usage) 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). |
Required Headers
“Content-Type”: “application/json”
“Authorization”, “Bearer Add Your Authentication Token here“
Example Submissions
Example Request
Create Donor Request
{
“identifier”: “DO6543212”,
“firstName”: “John”,
“lastName”: “Smith”,
“dateOfBirth”: “1987-01-01”,
“gender”: “MALE”
}
Example success 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 looking up order reports |