Integration guide

Production

https://health.yoti.com/admin-api

Retrieve results

https://health.yoti.com/admin-api/v1/results?fromId=0

Retrieve anonymised results

https://health.yoti.com/admin-api/v1/anonymised-results?fromId=0

Pre registration

https://health.yoti.com/admin-api/v1/pre-registrations

Collection

Creating a sample.

Pre registration

Add your customer’s information before testing.

Results anonymised

Receive a generic report.

Results full

Receive a detailed report including user information.

Self registration

Integrate with other systems you are using to send customers their invites to self-register. This will allow you to get the unique urls per customer. The Self-registration API takes a flag that you can choose if the email is sent or not via the Health Portal.

Authorization

API Key to call the Health API. This should be sent as a bearer token.

Content-Type

application/json

Email

Email address

Phone

Phone number format

Date of birth

YYYY-MM-DD

org_id

Number

Your Org ID.

fullName

String

The full name of the customer.

phoneNumber

Number

The phone number of the customer.

dateOfbirth

Date

The date of birth of the customer. This must be in the format: YYYY-MM-DD.

email

String

The email address of the customer.

type

String

SELF_REGISTRATION, SELF_SWAB, HOME_TEST, HOME_TEST_UNVERIFIED

send email

Boolean

Send customer an email.

testingScheme

String

TEST_TO_RELEASE, DAY_2. Leave blank for STANDARD

remaining

Number

Reports how many records are left to retrieve.

lastID

Number

Reports the ID of the last record returned in this response.

records

Array

A list of records containing test results and personal data if not anonymised.

record.id

Number

The ID of this record.

record.identityDetails

Object

Identity details of the user being tested.

record.testDetails

Object

Details about the test and its result.

record.symptoms (optional)

Object

Reported symptoms if they were collected at time of swabbing.

identityVerified

❌

Boolean

Indicates whether a photo ID was verified for the user being tested.

fullName

✅

Number

The full name of the user being tested. Includes first and last name and optionally middle names. If the split out name is also available the below given names and family name will also be populated.

givenNames

✅

String

This includes first name and middle names if provided.

familyName

✅

String

Family name of the user being tested.

dateOfBirth

✅

String

The date of birth of the user being tested in the form: YYYY-MM-DD.

gender

✅

String

The gender of the user being tested. Possible values:

• MALE

• FEMALE

• TRANSGENDER

• OTHER

nationality

✅

String

Nationality of the user being tested as an ISO/ICAO alpha-3 country code.

healthNumber

✅

String

Health number (e.g. NHS number) of the user being tested.

homeAddress

✅

Object

The home address of the user being tested. This is the address, post code and country. See below*.

email

✅

String

Email of the user being tested.

phoneNumber

✅

String

Phone number of the user being tested.

contactAddress

✅

Object

The contact address of the user being tested. This is the address, post code and country.

dateOfArrival

✅

String

Timestamp (UTC) of the date of arrival provided in the RFC3339 format, for example “2018-09-14T21:19:10Z”

countryFrom

✅

String

The country the user has come from.

countriesVisited

✅

Array

A list of the countries that a user has visited.

flightNumber

✅

String

Flight number

departureDate

✅

String

Timestamp (UTC) of the departure date provided in the RFC3339 format, for example “2018-09-14T21:19:10Z”

vaccinationStatus

✅

String

• None

• Partial

• Complete

• Exempt

ethnicity

✅

String

• BLACK - AFRICAN

• BLACK - CARIBBEAN

• BLACK - OTHER

• CHINESE

• INDIAN

• PAKISTANI

• WHITE

• WHITE AND ASIAN

• WHITE AND BLACK AFRICAN

• WHITE AND BLACK CARIBBEAN

• WHITE BRITISH

• WHITE IRISH

• WHITE OTHER

• ISC - UNSPECIFIED

• ANY OTHER ETHNIC CATEGORY

• ANY OTHER MIXED GROUP

• OTHER / MIXED

• UNKNOWN

documentDetails

✅

String

• DOCUMENT_TYPE

• ISSUING_COUNTRY

• DOCUMENT_NUMBER

• EXPIRATION_DATE

• ISSUING_AUTHORITY

addressLine1

String

AddressLine1 is the first line of the address

addressLine2

String

AddressLine2 is the first line of the address

addressLine3

String

AddressLine3 is the first line of the address

addressLine4

String

AddressLine4 is the first line of the address

postalCode

String

Postcode

countryIso

String

CountryIso is the country where this address is in ISO-3166-1 alpha-3 format.

uniqueId

❌

String

Contains an RFC 4122-compliant UUID which identifies a single test.

testMethod

✅

String

Possible values are: “NAAT”, “RT-PCR”, “LFT”.

manufacturer

✅

String

Reports who is the manufacturer of the test.

testTypeIdentifier

✅

String

Uniquely identifies the test in case there are different tests with the same method from the same manufacturer.

testingOrg

❌

String

Your organisation.

sampleCollectAt

❌

String

Timestamp (UTC) at which the sample was collected, provided in the RFC3339 format, for example “2018-09-14T21:19:10Z”

resultReportedAt

❌

String

Timestamp (UTC) at which the results were reported, provided in the RFC3339 format, for example “2018-09-14T21:19:10Z”

testingMachine

✅

Object

If configured, this will report what machine was used for processing the test.

testingMachine.id

✅

String

A unique ID to identify the machine. Could be a serial number or a UUID.

testingMachine.name

✅

String

A name to quickly identify what machine was used. Example values: "MyGoPro", "ThermoFisher", "TestingCube", "GeneMeTestingMachine".

location

✅

Object

The location at which the test was carried out. This is the address, post code and country.

cqScore

✅

String

Only returned when applicable for the testMethod. Cycle of quantification indicating the cycle number where the amplification curve meets a predefined criteria.

overallResult

❌

String

Reports the result of the test indicating if the virus or the antigen were detected. The result is marked as invalid in case it was not possible to carry out the test or in case the control indicates that the test was not valid. Possible values are:

• "VIRUS_OR_ANTIGEN_DETECTED"

• "VIRUS_OR_ANTIGEN_NOT_DETECTED"

• "INVALID"

400

Malformed request

500

Unexpected server error