API settings
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
| Permissions | Description |
|---|---|
| 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. |
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:
| Header | Description |
|---|---|
| Authorization | API Key to call the Health API. This should be sent as a bearer token. |
| Content-Type | application/json |
Retrieve the 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.
Results endpoint
GET https://health.yoti.com/admin-api/v1/results?fromId=0Anonymised results endpoint
GET https://health.yoti.com/admin-api/v1/anonymised-results?fromId=0Body explained
{ "remaining": 0, "lastId": 1223, "records": [] }//Anonymisedresults {}See below for explanation on each property.
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 .
PUT https://health.yoti.com/admin-api/v1/pre-registrationsAll fields are optional but one of the below fields is required:
| Field | Format |
|---|---|
| Email address | |
| Phone | Phone number format |
| Date of birth | YYYY-MM-DD |
Body explained
{ "phone": "07474747474", "email": "sample@email.com", "fullName": "Firstname Middlename Lastname", "dateOfBirth": "2000-01-20", "documentDetails": { "documentType": "PASSPORT", "issuingCountry": "GBR", "documentNumber": "<<<SOME<<MRZ<<<<<<09<<<" }, "homeAddress": { "addressLine1": "Flat 7", "addressLine2": "25 Long Road", "addressLine3": "City", "postalCode": "EH1 1AA", "countryIso": "GBR" }, "givenNames": "Firstname Middlename", "familyName": "Lastname", "gender": "MALE", "nationality": "GBR", "healthNumber": "123", "birthNumber": "123", "stayingAddress": { "addressLine1": "Flat 7", "addressLine2": "25 Long Road", "addressLine3": "City", "postalCode": "EH1 1AA", "countryIso": "GBR" }, "dateOfArrival": "2020-12-31T00:00:00Z", "countryFrom": "GBR", "countriesVisited": "GBR", "flightNumber": "12", "departureDate": null, "ethnicity": "UNKNOWN", "vaccinationStatus": "None"}