Token authentication

The Onfido API uses token-based authentication. API tokens must be included in the header of all requests made to the API.

You can generate new tokens and find your existing ones in your Onfido Dashboard.

You can make requests using sandbox tokens to test our API before you go live.

Rate limits

Onfido's API enforces a maximum volume of requests per minute for all clients. Unless contractually agreed otherwise, the maximum rate is 400 requests per minute.

For sandbox requests, the rate limit is 30 requests per minute.

Any request over the limit will return a 429 Too Many Requests error.

Onfido offers region-specific environments: EU, US, and Canada. You can use these to store the data in your Onfido account at rest within a specific geographic region.

Regions have unique base URLs and API token formats for both live and sandbox environments.

Example error object

Applicant object

ID number object

The ID number array of objects is nested inside the applicant object.

Address object

The applicant address object is nested inside the applicant object.

postcode and country are required fields if an address is provided for an applicant. For US addresses, state is also a required field.

Most addresses will contain information such as flat_number. Make sure they are supplied as separate fields, and do not try and fit them all into the street field. Doing so is likely to affect check performance.

Alternatively, you can provide addresses in the form line1, line2 and line3 if you're creating a check with an Identity Enhanced report. If you provide address data in this form, Onfido uses a third-party subprocessor for address cleansing.

Location object

The location object is nested inside the applicant object.

If country_of_residence is not provided in the request, it will be inferred from the IP address which may result in an incorrect value.

If you submitted location during document upload, it will not be returned here.

Forbidden characters

For addresses the following characters are forbidden:

!$%^*=<>

For names the following characters are forbidden:

^!#$%*=<>;{}"

Create applicant

Creates a single applicant. Returns an applicant object.

When you create an applicant, some characters are forbidden. You should remove any duplicate whitespaces before creating an applicant, otherwise this may result in a data comparison failure.

The minimum required (and recommended) applicant data depends on the type of report requested. For example, for Document reports.

Request body parameters

location

You must provide location information for each end user as this determines the necessary consent required in order to process a verification.

You can specify the IP address and the country of residence (3 character ISO country code) of the applicant in the location object.

...
"location": {
        "ip_address": "127.0.0.1",
        "country_of_residence": "GBR"
    }
...

You can also provide location information during document upload.

If you submit location information in multiple requests, the document upload location will take precedence.

consents

Where required, you must collect end user consent before creating a check with Onfido. If you do not, Onfido is unable to process an applicant's data and complete a verification.

Exact consent requirements are linked to the location of the end user. You must specify an applicant's location in the location parameter when creating an applicant or uploading a document.

• privacy_notices_read

End users located in the United States, must read the Privacy Notices and Terms of Service before giving consent for Onfido.

granted should be set to true after gaining the necessary consent from the applicant. If it's set to false, or the parameter is not provided, all check creation requests will fail with a validation error.

...
"consents": [
         {
            "name": "privacy_notices_read",
            "granted": true
        }
    ]
...

You can also provide consents when updating an applicant.

Document object

Retrieve document

Retrieves a single document. Returns a document object.

Live photo object

Live video object

During the video recording end users are asked to perform randomly generated actions, represented in challenge. Challenges always have 2 parts recite and movement, but the order in which these happen can vary. The order of the challenges is maintained in the live video object. recite asks the user to say 3 randomly generated digits, whereas movement asks the user to look over their right or left shoulder.

Download live video frame

Instead of the whole video, a single frame can be downloaded using this endpoint. Returns the binary data representing the frame.

Frame extraction failed

If a frame cannot be extracted from the live video, a frame_extraction_failed response will be returned.

Frame extraction unavailable

If the extraction feature is temporarily unavailable, a frame_extraction_unavailable response will be returned instead.

Check object

Check status

Document report: Object

We host a separate page which contains a detailed description of the Document report object values from an API user's perspective.

Results

The result field indicates the overall report result. Possible values for Document reports are clear and consider:

Sub-results

The sub_result field indicates a more detailed result, and is unique to Document reports. Possible values of sub_result are as follows:

Document report: Breakdowns

Breakdowns can have the values clear, consider and null.

A breakdown will have the result consider when at least one sub-breakdown contains a consider or unidentified result. For example, a consider result for the mrz sub-breakdown will produce a consider result for the data_validation breakdown. This will then also set the report sub_result value to suspected.

A breakdown will have the result null when it has not been completed, or is not available. For example, issuing_authority will return null if NFC is not available or inconclusive.

Some breakdowns contain sub-breakdowns. For example, the image_integrity breakdown comprises the sub-breakdowns supported_document, image_quality, colour_picture and conclusive_document_quality.

The possible values for sub-breakdowns are clear, consider, null and unidentified.

Breakdown order priority

Breakdown sub-results have the following order of priority:

rejected->suspected->caution->clear

For example, a caution sub-result will only ever be asserted when the following conditions are met:

• no individual breakdown has caused a rejected or suspected sub-result
• a breakdown which maps to a caution sub-result has been flagged

Breakdown mapping

Breakdowns and sub-breakdowns are mapped to particular sub-results. Certain mappings can be changed, where possible, depending on your configuration.

Note: Some breakdowns have sub-breakdowns that are mapped to different sub-results. For example, in the Data Validation breakdown, gender, document_numbers, expiry_date, date_of_birth, mrz and barcode map to suspected whereas document_expiration maps to caution.

Note: When a sub-breakdown mapped to a rejected sub-result is flagged, all other breakdowns and the document properties will be omitted from the response object.

Breakdown descriptions and logic

data_comparison:

Asserts whether data on the document is consistent with data provided when creating an applicant through the API. The White String Similarity Algorithm is used on the name fields. The algorithm produces a value between 0 and 1 based on how close a name is to another. Data comparison will fail if the value produced does not exceed our 0.5 threshold value. The match score is not returned. The purpose of this inexact matching is to avoid unnecessary failures if the names are mathematically close enough. Special characters in the name fields are transliterated by the algorithm, i.e. Ã becomes A. Configurable to allow for the process of special characters.

This breakdown can be switched off if needed. In this case, data_comparison itself and all its sub-breakdowns return null.

The following sub-breakdowns are used:

• last_name ¹
• first_name
• date_of_birth

1. last_name is not compared against the spouse_name, widow_name or given_name extracted data fields.

data_validation:

Asserts whether the format and length of the fields are correct for that document type. Uses the following sub-breakdowns:

• gender
• date_of_birth
• document_numbers
• document_expiration ¹
• expiry_date ²
• mrz
• barcode

1. If this is flagged, the document has expired. Onfido uses UTC as a fixed reference point for the current date and time when the dates are compared.
2. If this is flagged, the expiration date has the incorrect format or the date is in the past.

age_validation:

Asserts whether the age calculated from the document’s date of birth data point is greater than or equal to the minimum accepted age set at account level. The default minimum accepted age is 16 years. Configurable to set a different minimum age value. Onfido uses UTC as a fixed reference point for the current date and time when the applicant's age is calculated.

Uses the following sub-breakdown:

• minimum_accepted_age

image_integrity:

Asserts whether the document was of sufficient quality to verify. Uses the following sub-breakdowns:

• image_quality:

  Asserts whether the quality of the image was sufficient for processing.

• conclusive_document_quality:

  A result of clear for this sub-breakdown will assert if the document was of enough quality to be able to perform a fraud inspection. A result of consider will mean that even if sub breakdowns of visual_authenticity fail, we cannot positively say the document is fraudulent or not (in cases such as parts of the document are not visible).

• supported_document:

  Asserts whether the submitted document is supported. Takes value of clear or unidentified.

• colour_picture:

  Asserts whether the image was a colour one. A black and white picture will map to a caution Document report sub-result. Configurable to map to rejected.

visual_authenticity:

Asserts whether visual (non-textual) elements are correct given the document type. Uses the following sub-breakdowns:

• fonts:

  Fonts in the document don’t match the expected ones.

• picture_face_integrity:

  The pictures of the person identified on the document show signs of tampering or alteration. In most cases this will focus on the primary picture yet it may also apply to the secondary and tertiary pictures when documents contain them.

• template:

  The document doesn’t match the expected template for the document type and country it is from.

• security_features:

  Security features expected on the document are missing or wrong.

• original_document_present:

  The document was not present when the photo was taken. For example, a photo of a photo of a document or a photo of a computer screen. Configurable to map to caution instead of suspected.

• digital_tampering:

  Indication of digital tampering in the image (for example, name altered).

• other:

  This sub-breakdown is returned for backward compatibility reasons. Its value will be consider when at least one of the other breakdowns is consider, and clear when all the other breakdowns are clear.

• face_detection:

  No face was detected on the document.

data_consistency:

Asserts whether data represented in multiple places on the document is consistent. For example, between MRZ lines and OCR extracted text on passports. Uses the following sub-breakdowns:

• multiple_data_sources_present¹
• document_type
• gender
• date_of_expiry
• nationality
• issuing_country
• document_numbers
• date_of_birth
• last_name
• first_name

1. multiple_data_sources_present is for cases where we don’t obtain a US barcode because it wasn’t extracted, wasn’t decoded, or wasn’t there at all (e.g. if the back of the document wasn’t available). It acts as a validation for the data_consistency breakdown: if 2 sources are present, then data consistency is possible and the other sub-breakdowns are enabled. multiple_data_sources_present can be disabled if needed. In this case, it will be returned as null and have no impact on the sub-result.

police_record:

Asserts whether the document has been identified as lost, stolen or otherwise compromised. Applies to all UK documents or any document that has been reported stolen in the UK.

compromised_document:

Asserts whether the image of the document has been found in our internal database of compromised documents.

issuing_authority:

Asserts whether data on the document matches the issuing authority data. Uses the following sub-breakdowns:

• nfc_active_authentication:

  Asserts whether the document NFC chip is original or cloned.

• nfc_passive_authentication:

  Asserts whether the document NFC chip data was tampered.

1. You can configure your account to always trigger Visual Document Verification if nfc_active_authentication is returned as null (even if nfc_passive_authentication is clear). In this case, the visual authentication, image integrity and data consistency checks will be performed and the results returned in the breakdowns.

Document report: Breakdown reasoning

We will return a reason whenever a report flags for one of the following breakdowns:

• visual_authenticity : original_document_present

• image_integrity : conclusive_document_quality

• image_integrity : image_quality

This works by returning the contributing reason and corresponding fail result (a consider result) in the breakdown properties.

There can be more than one reason per breakdown, as they aren’t mutually exclusive.

All other signals and potential reasons will be omitted.

The following diagram illustrates this logic:

Original Document Present reasons:

photo_of_screen - When we can see that the applicant's document is on a physical screen or device, e.g. when the device is visible, software applications are seen, a computer cursor is present, or the pixels on the image appearing to have a different texture than expected

screenshot - When the applicant has used their mobile phone, tablet, or computer to take a photo within the device, e.g. when software applications are seen, the time and mobile provider are visible, or any digitally added component that wouldn't be seen on a physical document, such as an upload icon

document_on_printed_paper - when the applicant has previously captured an image of the document, printed it out, and has now taken a photo of this print out to upload, e.g. when the edges of the paper are visible, when there are fold creases on the paper, or the document's edges blending into the background and appearing flat

scan - When the document has clearly been captured using a scanner and there are visible indicators of this, e.g. unusual shadows on the edges of the document, or written text around the document

Conclusive Document Quality reasons:

obscured_data_points - This refers to when data points are obscured to the point that we cannot confirm if the fonts match the expected ones

obscured_security_features - This refers to whenever a critical security feature is obscured. This can also refer to when the holder's wet signature, necessary for the document to be valid, is not present

abnormal_document_features - One of 3 reasons: (1) OCR Assisted Scans (i.e. when you're able to move the mouse and highlight part of text), (2) Severely Washed out Background, (3) Overlapping Text

watermarks_digital_text_overlay - Any digital text or electronic watermarks on the document

corner_removed - If the corner has been physically cut off. This can be found on some documents that are no longer valid

punctured_document - A punched hole is present. This can be found on DLs that are no longer valid, for example

missing_back - When the back of a document is needed for processing (e.g. for key data points to extract), but is not available (e.g. if the same front was uploaded twice)

digital_document - When a document has been published digitally, there aren’t enough security features to review so we cannot perform a full fraud assessment

Image Quality reasons:

dark_photo - When an image of the document is too dark to be able to see data points

glare_on_photo - When there is light reflecting on the document causing glare to obstruct data points

blurred_photo - When data points are blurred and no reference can be made elsewhere in the document or if the data points are too blurry and 'they could be something else' (e.g. "I" could be "1", "B" could be "8")

covered_photo - When data points have been covered either by the applicant or by another object such as a sticker

other_photo_issue - Any other reason not listed, such as when holograms are obscuring data points

damaged_document - When a document is damaged and we are unable to make out data points

incorrect_side - When the incorrect side of a document has been uploaded, and we have not received the front

cut_off_document - When data points are not included in the image due to the document being cut off (i.e. out of the frame of the image)

no_document_in_image - If no document has been uploaded or there is a blank image

two_documents_uploaded - When 2 different documents are submitted in the same check

Facial Similarity Photo

Facial Similarity Photo: Object

The following table describes the unique fields returned in this version of the Onfido API for a completed Facial Similarity Photo report:

1: source_integrity may contain reasons under the properties bag (see Facial Similarity Photo: Source Integrity)

2: face_match contains a score value and document_id unique identifier under the properties bag (see Facial Similarity Photo: Face Match properties)

3: spoofing_detection contains a score value under the properties bag (see Facial Similarity Photo: Spoofing Detection Score)

Facial Similarity Photo: Breakdowns

Facial Similarity Photo: Source Integrity

We will return a reason whenever a report flags for source_integrity. This works by returning the contributing reason and a consider result in the source_integrity breakdown properties. There can be more than one reason, because they aren’t mutually exclusive. All other signals and potential reasons will be omitted.

For Facial Similarity Photo, the source_integrity sub-breakdown is composed of the following properties:

• digital_tampering - when evidence is found that the image was manipulated by Photoshop, or other software
• fake_webcam - when evidence is found that a fake webcam was used
• time_of_capture - when evidence is found that the live photo was taken more than 24 hours before live photo upload
• emulator - when evidence is found that an Android emulator was used
• reasons - additional comma separated details such as the exact digital tampering software used, or the name of the fake webcam

Facial Similarity Photo: Face Match properties

The face_match breakdown contains a properties object with a score value and document_id unique identifier.

• The score value is a floating point number between 0 and 1 that expresses how similar the two faces are, where 1 is a perfect match.

  If the face matching algorithm fails to detect a face, the score property will not be present and the face matching task will be done manually. The score only measures how similar the faces are, and does not make an assessment of the nature of the photo. If spoofing (such as photos of printed photos or photos of digital screens) is detected the applicant will be rejected independently of the face match score.

• document_id returns the UUID for the document containing the extracted face that was used for face matching.

  If no face is detected, no document is recorded and the property is returned as null.

Facial Similarity Photo: Spoofing Detection Score

The spoofing_detection breakdown contains a properties object with a score value. This score is a floating point number between 0 and 1. The closer the score is to 0, the more likely it is to be a spoof (i.e. photos of printed photos, or photos of digital screens). Conversely, the closer it is to 1, the less likely it is to be a spoof.

Photo Fully Auto

Photo Fully Auto: Object

The following table describes the unique fields returned in this version of the Onfido API for a completed Photo Fully Auto report:

1: source_integrity may contain reasons under the properties bag (see Source Integrity for Photo Fully Auto)

2: face_match contains a score value and document_id unique identifier under the properties bag (see Face Match properties for Photo Fully Auto)

3: spoofing_detection contains a score value under the properties bag (see Spoofing Detection Score for Photo Fully Auto)

Photo Fully Auto: Breakdowns

Photo Fully Auto: Source Integrity

We will return a reason whenever a report flags for source_integrity. This works by returning the contributing reason and a consider result in the source_integrity breakdown properties. There can be more than one reason, because they aren’t mutually exclusive. All other signals and potential reasons will be omitted.

For Photo Fully Auto, the source_integrity sub-breakdown is composed of the following properties:

• digital_tampering - when evidence is found that the image was manipulated by Photoshop, or other software
• fake_webcam - when evidence is found that a fake webcam was used
• time_of_capture - when evidence is found that the live photo was taken more than 24 hours before live photo upload
• emulator - when evidence is found that an Android emulator was used
• reasons - additional comma separated details such as the exact digital tampering software used, or the name of the fake webcam

Photo Fully Auto: Face Match properties

The face_match breakdown contains a properties object with a score value and document_id unique identifier.

• The score value is a floating point number between 0 and 1 that expresses how similar the two faces are, where 1 is a perfect match.

  If the face matching algorithm fails to detect a face, the score property will not be present. The score only measures how similar the faces are, and does not make an assessment of the nature of the photo. If spoofing (such as photos of printed photos or photos of digital screens) is detected the applicant will be rejected independently of the face match score.

• document_id returns the UUID for the document containing the extracted face that was used for face matching.

  If no face is detected, no document is recorded and the property is returned as null.

Photo Fully Auto: Spoofing Detection Score

The spoofing_detection breakdown contains a properties object with a score value. This score is a floating point number between 0 and 1. The closer the score is to 0, the more likely it is to be a spoof (i.e. photos of printed photos, or photos of digital screens). Conversely, the closer it is to 1, the less likely it is to be a spoof.

If the anti-spoofing algorithm fails to detect a face, the score property will not be present.

Facial Similarity Video

In the Facial Similarity Video report, live videos are collected and uploaded by one of the Onfido SDKs (iOS, Android or JS).

In addition to confirming the two faces match, Facial Similarity Video assesses active liveness by asking users to repeat randomly generated numbers and perform a random head movement. This prevents impersonation - for example masks, and deep fakes displayed on digital screens. This process is reflected in visual_authenticity, which is composed of the sub-breakdowns spoofing_detection and liveness_detected. See Facial Similarity Video Object and Facial Similarity Video Breakdowns.

In order for a Facial Similarity Video report to complete automatically, the user needs to turn their head in the correct direction and correctly say the 3 randomly generated digits in one of our supported languages (see table below).

SDK localization

We recommend that you localize the strings if you're using one of the Onfido SDKs, so the user is more likely to understand the liveness headturn and speaking instructions.

The Onfido voice processor will attempt to detect the language the user is speaking. This will be more successful if you pass the code for the expected language to the locale mechanism, in any of the Onfido SDKs:

• iOS SDK - pass the onfido_locale parameter
• Android SDK - pass the onfido_locale parameter
• Web SDK - pass the locale parameter

Some string localisations are available out of the box, but this differs depending on the SDK.

You can also provide your own custom translations to your users.

Facial Similarity Video: Object

The following table describes the unique fields returned in this version of the Onfido API for a completed Facial Similarity Video report:

1: source_integrity may contain reasons under the properties bag (see Facial Similarity Video: Source Integrity)

2: face_match contains a score value and document_id unique identifier under the properties bag (see Facial Similarity Video: Face Match properties)

3: spoofing_detection contains a score value under the properties bag (see Facial Similarity Video: Spoofing Detection Score)

Facial Similarity Video: Breakdowns

Facial Similarity Video: Source Integrity

We will return a reason whenever a report flags for source_integrity. This works by returning the contributing reason and a consider result in the source_integrity breakdown properties. There can be more than one reason, because they aren’t mutually exclusive. All other signals and potential reasons will be omitted.

For Facial Similarity Video, the source_integrity sub-breakdown is composed of the following properties:

• fake_webcam - when evidence is found that a fake webcam was used
• emulator - when evidence is found that an Android emulator was used
• challenge_reuse - when evidence is found that the video was uploaded in an attempt to circumvent the randomness of the speaking and head turn challenges
• reasons - additional comma separated details, such as the name of the fake webcam

Facial Similarity Video: Face Match properties

The face_match breakdown contains a properties object with a score value and document_id unique identifier.

• The score value is a floating point number between 0 and 1 that expresses how similar the two faces are, where 1 is a perfect match.

  If the face matching algorithm fails to detect a face, the score property will not be present and the face matching task will be done manually. The score only measures how similar the faces are, and does not make an assessment of the nature of the live video. If spoofing (such as videos of digital screens, masks or print-outs) is detected the applicant will be rejected independently of the face match score.

• document_id returns the UUID for the document containing the extracted face that was used for face matching.

  If no face is detected, no document is recorded and the property is returned as null.

Facial Similarity Video: Spoofing Detection Score

The spoofing_detection breakdown contains a properties object with a score value. This score is a floating point number between 0 and 1. The closer the score is to 0, the more likely it is to be a spoof (i.e. videos of digital screens, masks or print-outs). Conversely, the closer it is to 1, the less likely it is to be a spoof.

The score value is based on passive facial information only, regardless of whether or not the user said the expected digits or turned their head in the correct direction. For example, a user who performs no action but is a real person should receive a score close to 1.

Known Faces report

This section contains API documentation for the Known Faces report. You can also read our product documentation.

Each applicant you run a Known Faces report against must have an uploaded live photo or live video.

If no live photo or live video is found, the Known Faces report will be automatically withdrawn and return an error in the report properties:

"properties":{
    "reason": "Report withdrawn due to missing media (photo or video) required for processing."
}

No matches will be returned against any permanently deleted applicants.

To request a Known Faces report as part of a check in the API, use the report_names field (which takes an array of strings):

"report_names": ["known_faces"]

Required applicant data

For Known Face reports, first_name and last_name must be provided but can be dummy values if you don't know an applicant's name.

Known Faces: Object

The following table describes the unique fields returned in this version of the Onfido API for a completed Known Faces report:

1. null is returned when image_integrity is "consider". This is because, when no face is detected in the input media, there is nothing to match against previously seen faces.

Known Faces: Breakdowns

Known Faces: Score

The Known Faces response will return any matching applicant IDs as entries inside a matches array under a properties bag. Each applicant ID has a corresponding score and the media type (for example live_photos or live_videos), and the corresponding UUID for that media type. For example, the live photo or live video ID.

This score is a floating point number between 0 and 1 that expresses how similar the two faces are, where 1 is a perfect match.

"matches": [
  {
    "applicant_id": "NTH_MATCHED_APPLICANT_ID",
    "score": 0.9915,
    "media_id": "LIVE_PHOTO_ID",
    "media_type": "live_photos"
  }
]

If any matches are found, the response will also contain "result": "consider".

Identity Enhanced report

This section contains API documentation for the Identity Enhanced report. You can also read our product documentation, which includes a list of the sources used in the Identity Enhanced report, with corresponding definitions, and the report logic.

To request an Identity Enhanced report as part of a check in the API, use the report_names field (which takes an array of strings):

"report_names": ["identity_enhanced"]

Required applicant data

For Identity Enhanced reports, the following applicant data must be provided:

first_name

last_name

dob

address[]state (US only)

address[]postcode (ZIP code in US)

address[]country (must be a 3-letter ISO code e.g. "GBR")

Recommended applicant data

address[]street The applicant address object is nested inside the applicant object. If you create an applicant object with an address, you must provide postcode and country, and state for US addresses.

Supported countries for Identity Enhanced

You can review the full list of supported countries for Identity Enhanced reports. The column Identity Enhanced Report on that page lists supported and unsupported countries.

This is not a list of documents that Onfido supports: you can review that list separately.

Identity Enhanced report custom logic

We've moved this content.

Watchlist AML

The Watchlist AML report provides a granular breakdown of any records found when screening global watchlists and media sources. These include:

• sanction: Government and International Organisations Sanctions Lists
• politically_exposed_person: Proprietary database of Politically Exposed Persons sourced from government lists, websites and other media sources
• legal_and_regulatory_warnings: Law-Enforcement and Regulatory bodies Monitored Lists (including Terrorism, Money Laundering and Most Wanted lists)
• adverse_media: Negative events reported by publicly and generally available media sources

Records

If no match is found against the subject, the records field will read [] and the overall result will be clear.

If one or more matches are found, each match will be returned under records and the overall result will be consider.

Where applicable, if multiple values are found from the raw response, string concatenation with a delimiter of ", " is used.

Entity fields are additional, optional fields so they may not be present in the final result.

Required applicant data

For watchlist_aml reports, first_name and last_name must be provided.

Recommended applicant data

dob

address[]postcode (ZIP code in US)

address[]country

address[]state (required for US addresses)

The applicant address object is nested inside the applicant object. If you create an applicant object with an address, you must provide postcode and country, and state for US addresses.

Watchlist Enhanced

The Watchlist Enhanced report provides a granular breakdown of any records found when screening global watchlists. These include the following breakdowns:

• sanction: Government and International Organisations Sanctions Lists.
• politically_exposed_person: Proprietary database of Politically Exposed Persons sourced from government lists, websites and other media sources.
• monitored_lists: Law-Enforcement and Regulatory bodies Monitored Lists (including Terrorism, Money Laundering and Most Wanted lists).
• adverse_media: Negative events reported by publicly and generally available media sources.

Records

If no match is found against the subject, the records field will read [] and the overall result will be clear.

If one or more matches are found, each match will be returned under records and the overall result will be consider. Each event will correspond to a relevant category of list, which drives one of the breakdowns.

Required applicant data

For watchlist_enhanced reports, first_name and last_name must be provided.

Recommended applicant data

dob

address[]postcode (ZIP code in US)

address[]country

address[]state (required for US addresses)

The applicant address object is nested inside the applicant object. If you create an applicant object with an address, you must provide postcode and country, and state for US addresses.

Date of birth

Submitting a date_of_birth with the name is optional but recommended, to narrow the search of the relevant individual.

More than one date of birth might be found per match due to the nature of the data sources, such as newspaper articles, which might include someone's age but not their full date of birth.

Address

Submitting an address with the name is also optional but recommended. This will narrow the search to the country specified in the address, for all politically_exposed_person and adverse_media breakdown matches except Money Laundering and Terrorist related matches. This will not filter sanction breakdown matches.

If a match is found with either Sanctions, Money Laundering or Terrorist related events, all the other events of that match will be returned, even if the other events are not related to the country specified in the address.

If a match is found but the date_of_birth or address fields are null, this means there is no date_of_birth or address data on file associated with that match.

Watchlist Standard

The Watchlist Standard report provides a granular breakdown of any records found when screening global watchlists. These include:

• sanction: Government and International Organisations Sanctions Lists.
• politically_exposed_person: Proprietary database of Politically Exposed Persons sourced from government lists, websites and other media sources.
• legal_and_regulatory_warnings: Law-Enforcement and Regulatory bodies Monitored Lists (including Terrorism, Money Laundering and Most Wanted lists).

You can use a Watchlist PEPs Only report to search only PEPs lists, or a Watchlist Sanctions Only report to search only sanctions and warnings lists. The Watchlist Standard report will search all types.

Records

If no match is found against the subject, the records field will read [] and the overall result will be clear.

If one or more matches are found, each match will be returned under records and the overall result will be consider.

See Watchlist AML records for details of the possible fields.

Required applicant data

For watchlist_standard reports, first_name and last_name must be provided.

Recommended applicant data

dob

address[]postcode (ZIP code in US)

address[]country

address[]state (required for US addresses)

The applicant address object is nested inside the applicant object. If you create an applicant object with an address, you must provide postcode and country, and state for US addresses.

Proof of Address report

This section contains API documentation for the Proof of Address report. You can also read our product documentation, which contains a guide on the logic the Proof of Address report uses.

To request a Proof of Address report as part of a check in the API, use the report_names field (which takes an array of strings):

"report_names": ["proof_of_address"]

Supported issuing countries

Documents issued by the following countries are supported for a PoA report:

• United Kingdom
• European Economic Area (excluding Greece, Cyprus and Bulgaria)
• United States of America
• Canada
• New Zealand
• Australia
• Hong Kong
• Singapore
• Philippines
• Indonesia
• Vietnam
• Mexico
• Brazil
• Argentina

You must set the issuing_country field to the corresponding country when uploading the document via the document upload endpoint.

If the issuing_country field is not specified or is from an unsupported country, the document will be uploaded however it will not be processed and the report will complete with the status set to cancelled and the result set to null.

Applicants are able to upload documents from anywhere in the world, but the document must have been issued by a supported country and be a supported document for this report.

Required applicant data

For Proof of Address reports, the following applicant data must be provided:

first_name

last_name

address[]street

address[]town

address[]postcode

address[]country (must be a 3-letter ISO code e.g. "GBR")

The applicant address object is nested inside the applicant object. If you create an applicant object with an address, you must provide postcode and country, and state for US addresses.

Supported document types

The following document types are supported for a PoA report:

Proof of Address: Breakdowns

A PoA report is composed of the following 3 breakdowns:

Proof of Address: Properties

In addition, data points extracted from PoA documents are returned in the properties attribute.

Only the summary period or the issue date will be returned in the report properties attribute as they are mutually exclusive.

Proof of Address: Overall Result Logic

We've moved this content.

Right to Work: Document

Breakdowns

When a document is provided the Right to Work report result is determined by the right_to_work breakdown, which can have either a clear or consider result.

The right_to_work breakdown is informed by the applicant_has_the_right_to_work sub-breakdown which can have one of 3 results:

• clear (no known restrictions on right to work)
• consider (restrictions on right to work e.g. working hours)
• unidentified (no right to work)

The report result is also informed by breakdowns which signal fraud or image quality issues in the associated document.

Right to Work: Share code

Breakdowns

When a share code is provided the Right to Work report result is determined by the share_code_validation breakdown as well as the right_to_work breakdown.

The document_id sub-breakdown contains the document ID to retrieve the GOV.UK evidence document of the applicant's right to work using the retrieve document endpoint.

Driver's License Data Verification report

This section contains API documentation for the Driver's License Data Verification (DLDV) report. You can also read our product documentation.

To request a DLDV report as part of a check in the API, use the report_names field (which takes an array of strings):

"report_names": ["us_driving_licence"]

To upload document data, use the us_driving_licence field (which is an object containing all accepted fields for the DLDV report).

...
"report_names": ["us_driving_licence"],
"us_driving_licence":{
  "id_number": "<DRIVER_LICENCE_ID>",             // required
  "issue_state": "<TWO_LETTER_STATE_CODE>",       // required
  ...                                             // all other optional fields
  }
...

See optional document data for a table of the accepted optional fields in the us_driving_licence object for a DLDV report.

See create a check for a full list of the possible request body parameters.

If you use this report, Onfido will use a third-party subprocessor to verify driving license data against the American Association of Motor Vehicle Administrators (AAMVA) facilitated Department of Motor Vehicles (DMV) driver's license database.

Required applicant data

For DLDV reports, first_name and last_name must be provided.

Required document data

For DLDV reports, the following document data must be provided in the report request in the us_driving_licence field:

Optional document data

The following optional fields are also accepted in the us_driving_licence object:

Supported document types

• US driver's license
• US learner's permit or provisional license
• ID card

DLDV: Results

The result field indicates the overall report result. Any optional fields submitted in the report request will be accounted for in the final result.

Possible values for DLDV reports are clear, consider and unidentified:

* Onfido's third-party subprocessor uses fuzzy matching on the name fields during DLDV checks. This is because information can be provided in many different ways and errors in data submission or collection can be quite high. Fuzzy matching allows capturing data variations.

DLDV: Breakdowns

Breakdowns can have a clear or consider result. Breakdowns will only have a clear result when all included sub-breakdowns are clear.

Applicant Fraud report

Applicant Fraud is currently a BETA product. Please contact Client Support if you would like to find out more.

This section contains API documentation for the Applicant Fraud report. You can also read our product documentation.

To request an Applicant Fraud report as part of a check in the API, use the report_names field (which takes an array of strings):

"report_names": ["applicant_fraud"]

Required applicant data

For Applicant Fraud reports, the following applicant data must be provided:

• first_name and last_name
• a document or biometric media upload via the Onfido SDKs

Applicant Fraud: Results

The result field indicates the overall report result.

Possible values for Applicant Fraud reports are clear and consider:

In addition, any additional data and signals are returned in the properties attribute.

Applicant Fraud: Breakdowns

Breakdowns can have a clear or consider result.

Applicant Fraud: Properties

Data and signals collected about the device, IP, and geolocation are returned in the properties attribute.

Note: All properties can take the value null in addition to their corresponding list of possible values.

device object:

ip object:

geolocation object:

Webhook object

Event object

Attributes

Webhook event versioning

Refer to our API versioning guide for details on webhook event versioning.

Verifying webhook signatures

You should verify request signatures on your server to prevent attackers from imitating valid webhook events.

Each webhook you register will return a single secret token in the token field of the API response body, which is used to generate an HMAC using SHA-256. You only need to register a webhook once. The token for each webhook is also displayed on the Onfido Dashboard ‘Webhook Management’ page.

If possible, we recommend that you verify request signatures with our supported client libraries in your integration.

The following Onfido client libraries have support built in:

• Java

• Node

• Python

• Ruby

Using Onfido client libraries

You must initialise the verifier instance with your webhook’s secret token. For each webhook event, the verifier instance needs:

• the signature of the webhook (from the X-SHA2-Signature header)

• the body of the event request (must be in raw format, not decoded from JSON)

Manually

We provide a detailed guide in our Developer Hub for manually verifying webhook signatures.