Integration guide

This document will guide you through the configuration and implementation steps that are necessary in order for your backend to be able to retrieve user’s test results.

Before you start
Make sure you are all set up with a portal account.
Health overview

The integration steps are as follows:

  1. Authentication
  2. Retrieve the results
  3. Extra: Pre-registration

The health endpoint is listed below:

EnvironmentURL
Productionhttps://health.yoti.com/admin-api
Retrieve resultshttps://health.yoti.com/admin-api/v1/results?fromId=0
Retrieve anonymised resultshttps://health.yoti.com/admin-api/v1/anonymised-results?fromId=0
Pre registrationhttps://health.yoti.com/admin-api/v1/pre-registrations

Authentication

The health API uses an HTTP authentication scheme called ‘bearer authentication’. This involves security tokens called ‘bearer tokens’. They are the predominant type of access token used with OAuth 2.0. A resource should interpret a bearer token as "Give the bearer of this token access". The client must send this token in the Authorization header when making requests to protected resources.

Once you are onboard with us, login to your portal >> Head to "Settings" >> Type in an API key name with permissions enabled >> GENERATE KEY.

API settings

API settings
PermissionsDescription
CollectionCreating a sample.
Pre registrationAdd your customer’s information before testing.
Results anonymisedReceive a generic report.
Results fullReceive a detailed report including user information.
Self registrationIntegrate 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.

It is important that your API Key remains strictly confidential. It must be stored securely. We advise that you never commit any code containing your API Key, and never share it beyond the authorised party.

If you believe your API key has been compromised, please contact us as soon as possible. This can be done through your account manager or via our support desk by emailing clientsupport@yoti.com.

Header explained

The following elements are needed in the header:

HeaderDescription
AuthorizationAPI Key to call the Health API. This should be sent as a bearer token.
Content-Typeapplication/json

Collection

The collection endpoint allows you to create a sample via the api, instead of going through the normal bag collection flow.

HTTP
Copy

Body explained

JSON
Copy

Pre-registration

This PUT endpoint will allow you to add your customer’s information before testing to speed up collection flow. Once a pre-registration is added this allows the you to search for the customer’s pre-registered data using one of the lookup fields such as email, phone, dateOfBirth .

HTTP
Copy

All fields are optional but one of the below fields is required:

FieldFormat
EmailEmail address
PhonePhone number format
Date of birthYYYY-MM-DD

Body explained

JSON
Copy

###

Results

This GET endpoint allows you to retrieve the results of the tests performed within your organisation. Yoti gives you the option to collate anonymous results.

This endpoint will allow to fetch results from the given ID that is provided as the query parameter fromId. Specifying fromId=0 means fetching results from the start, the maximum limit is 400.

Hint The response will provide the lastId from which the next call should be made in order to fetch the remaining records (in case the response reports remaining>0).

Results full endpoint

HTTP
Copy

Anonymised results endpoint

HTTP
Copy

Body explained

JSON
Copy

See below for explanation on each property.

Self registration

This will allow you to send a self registration invite

HTTP
Copy
JSON
Copy
FieldTypeDescription
org_idNumberYour Org ID.
fullNameStringThe full name of the customer.
phoneNumberNumberThe phone number of the customer.
dateOfbirthDateThe date of birth of the customer. This must be in the format: YYYY-MM-DD.
emailStringThe email address of the customer.
typeStringSELF_REGISTRATION, SELF_SWAB, HOME_TEST, HOME_TEST_UNVERIFIED
send emailBooleanSend customer an email.
testingSchemeStringTEST_TO_RELEASE, DAY_2. Leave blank for STANDARD

Response body

JSON
Copy

Properties explained

Below describes each JSON property:

FieldTypeDescription
remainingNumberReports how many records are left to retrieve.
lastIDNumberReports the ID of the last record returned in this response.
recordsArrayA list of records containing test results and personal data if not anonymised.
record.idNumberThe ID of this record.
record.identityDetailsObjectIdentity details of the user being tested.
record.testDetailsObjectDetails about the test and its result.
record.symptoms (optional)ObjectReported symptoms if they were collected at time of swabbing.
FieldOptionalTypeDescription
identityVerified❌BooleanIndicates whether a photo ID was verified for the user being tested.
fullName✅NumberThe 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✅StringThis includes first name and middle names if provided.
familyName✅StringFamily name of the user being tested.
dateOfBirth✅StringThe 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✅StringNationality of the user being tested as an ISO/ICAO alpha-3 country code.
healthNumber✅StringHealth number (e.g. NHS number) of the user being tested.
homeAddress✅ObjectThe home address of the user being tested. This is the address, post code and country. See below*.
email✅StringEmail of the user being tested.
phoneNumber✅StringPhone number of the user being tested.
contactAddress✅ObjectThe contact address of the user being tested. This is the address, post code and country.
dateOfArrival✅StringTimestamp (UTC) of the date of arrival provided in the RFC3339 format, for example “2018-09-14T21:19:10Z”
countryFrom✅StringThe country the user has come from.
countriesVisited✅ArrayA list of the countries that a user has visited.
flightNumber✅StringFlight number
departureDate✅StringTimestamp (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

*Address explained:

FieldTypeDescription
addressLine1StringAddressLine1 is the first line of the address
addressLine2StringAddressLine2 is the first line of the address
addressLine3StringAddressLine3 is the first line of the address
addressLine4StringAddressLine4 is the first line of the address
postalCodeStringPostcode
countryIsoStringCountryIso is the country where this address is in ISO-3166-1 alpha-3 format.
FieldOptionalTypeDescription
uniqueId❌StringContains an RFC 4122-compliant UUID which identifies a single test.
testMethod✅StringPossible values are: “NAAT”, “RT-PCR”, “LFT”.
manufacturer✅StringReports who is the manufacturer of the test.
testTypeIdentifier✅StringUniquely identifies the test in case there are different tests with the same method from the same manufacturer.
testingOrg❌StringYour organisation.
sampleCollectAt❌StringTimestamp (UTC) at which the sample was collected, provided in the RFC3339 format, for example “2018-09-14T21:19:10Z”
resultReportedAt❌StringTimestamp (UTC) at which the results were reported, provided in the RFC3339 format, for example “2018-09-14T21:19:10Z”
testingMachine✅ObjectIf configured, this will report what machine was used for processing the test.
testingMachine.id✅StringA unique ID to identify the machine. Could be a serial number or a UUID.
testingMachine.name✅StringA name to quickly identify what machine was used. Example values: "MyGoPro", "ThermoFisher", "TestingCube", "GeneMeTestingMachine".
location✅ObjectThe location at which the test was carried out. This is the address, post code and country.
cqScore✅StringOnly 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"

Error codes

See error codes listed below:

Error codeDescription
400Malformed request
500Unexpected server error
Type to search, ESC to discard
Type to search, ESC to discard
Type to search, ESC to discard
Next to read:
What our clients say

Got a question? Contact us here.

On This Page
Integration guideAuthenticationHeader explainedCollectionBody explainedPre-registrationBody explainedResultsResults full endpointAnonymised results endpointBody explainedSelf registrationResponse bodyProperties explainedError codes