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 second for all clients. Unless contractually agreed otherwise, the maximum rate is 400 requests per minute (up to 7 requests per second with a burst of 14 requests).

For sandbox requests, the rate limit is 120 requests per minute (up to 2 requests per second with a burst of 4 requests).

Onfido uses the token bucket algorithm to handle usage.

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

Regions

Onfido offers region-specific environments: EU (default), 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 type in the id_numbers array uses the spelling "driving_license". The type for the Document resource in the API uses the spelling "driving_licence".

Addresses 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, if you're creating a check with an Identity KYC report on an applicant, you can provide addresses in the form line1, line2 and line3. If you provide address data in this form, Onfido uses a third-party subprocessor for address cleansing.

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.

The parameters required depend on whether you are planning to perform Standard or Express checks on this applicant. Standard checks require the applicant to provide their information using Onfido's applicant form, whereas Express checks are performed using data provided through the API.

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

Request body parameters

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.

This will be the frame extracted from the video where the end user is facing the camera. If no face can be detected, it will fallback to the first frame of the video.

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.

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.

Our newly expanded OpenAPI specification, which is currently in beta, is also a resource for understanding the Document report response object structure. We welcome feedback on this beta initiative under the 'Issues' tab on GitHub, or at openapi-feedback@onfido.com.

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. sub_result is only applicable to Document reports. Possible values are as follows:

Document report: Breakdowns

Breakdowns can have the values clear and consider.

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.

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 descriptions and logic

• police_record:

  Asserts whether the document has been identified as lost, stolen or otherwise compromised. Applies to all documents that have been reported as stolen or fraudulent to the UK Metropolitan Police.

  This breakdown is only returned if Police Record Checks are enabled for your account. Otherwise, the breakdown and its sub-breakdowns are returned as null and will not affect the final report result. To enable Police Record Checks, please contact Client Support.

• compromised_document:

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

• 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:

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

• data_validation:

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

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

1. If this is flagged, the document has expired.
2. If this is flagged, the expiration date has the incorrect format or the date is in the past.

• visual_authenticity:

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

  • 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).

  • 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.

  • security_features:

    Security features expected on the document are missing or wrong.

  • template:

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

  • fonts:

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

  • face_detection:

    No face was detected on the document.

  • 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.

• image_integrity:

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

  • 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.

  • 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.

  • image_quality:

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

• data_comparison:

  Establishes whether the data provided by the applicant matches the data extracted from the document. This breakdown is only returned if Comparison Checks are enabled for your account. Otherwise, the breakdown and its sub-breakdowns are returned as null and will not affect the final report result. To enable Comparison Checks, please contact Client Support.

  We compare the following fields:

  • first_name

  • last_name

  • date_of_birth

  • gender

    first_name and last_name can be configured to use a fuzzy or exact mechanism for the comparison. We take into account all available names for comparison, including spouse, widow or alias names.

    date_of_birth and gender will always be compared using an exact mechanism.

    Fuzzy comparison allows for greater flexibility during comparison, catering for discrepancies which may occur, for example, when an applicant uses their middle or spouse name, or there's been an extraction error.

    Note:

  • When an applicant hasn’t provided data the sub-breakdown result is null for the missing field

  • When an applicant has provided names but names have not been extracted from the document, the sub-breakdown result is consider

  • When an applicant has provided date of birth and/or gender, but these fields have not been extracted from the document, the sub-breakdown result is null

    Any other sub-breakdowns present under data_comparison in the document report object exist only for legacy reasons.

• age_validation:

  Asserts whether the age calculated from the document’s date of birth data point is greater than or equal the minimum accepted age set at account level. The standard threshold is 16 years old but you can write to your Onfido contact to have this changed.

Breakdown properties

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

• Image Integrity - Image Quality

• Image Integrity - Conclusive Document Quality

• Visual Authenticity - Original Document Present

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.

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 two different identity documents are submitted in the same check

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 - This refers to when something other than obscuration of data points and security features makes the document insufficient to be assessed (i.e. poor image resolution, bad lighting, distortions due to capturing devices, misalignment due to cracks, visual alterations due to cases/laminates, some stickers etc.)

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

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

Facial Similarity Standard

The Facial Similarity Standard report uses live photos. The photo needs to be a live photo taken at the time of check submission, so that it can assess whether the holder of the identity document is the same person as the one on the document.

Facial Similarity Standard: Object

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

Facial Similarity Standard: Breakdowns

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 Standard, 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
• sanctioned_document_country - when a document is issued by a country subject to comprehensive US sanctions (you can find the list of countries here). The report (either in conjunction with or separate from a document report) will return a consider result, accompanied by a reasons property clarifying that it is not supported due to sanctions
• reasons - additional comma separated details such as the exact digital tampering software used, or the name of the fake webcam

Facial Similarity Standard: Properties

The score property is a 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 tampering is detected, the applicant will be rejected independently of the score. Examples of tampering are photos of printed photos, or photos of digital screens.

Facial Similarity Video

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

In addition to confirming the two faces match, Facial Similarity Video assesses liveness by asking users to repeat randomly generated numbers and perform a random head movement. This prevents impersonation - for example photos of photos, or photos of screens. This process is reflected in visual_authenticity, which is composed of the sub-breakdowns spoofing_detection and liveness_detected. See the sections 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:

Facial Similarity Video: Breakdowns

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
• sanctioned_document_country - when a document is issued by a country subject to comprehensive US sanctions (you can find the list of countries here). The report (either in conjunction with or separate from a document report) will return a consider result, accompanied by a reasons property clarifying that it is not supported due to sanctions
• reasons - additional comma separated details, such as the name of the fake webcam

Facial Similarity Video: Properties

The score property is a 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 video. If tampering is detected, the applicant will be rejected independently of the score. Examples of tampering are videos of digital screens, videos of masks, videos of print outs.

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, live video or motion capture.

If no live photo, live video or motion capture 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, video or motion capture) required for processing."
}

No matches will be returned against any permanently deleted applicants.

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 ID 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.

For example:

"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".

The score property is number from 0 to 1, where 1 is a perfect match. The higher the score the more similar the two applicants are. score is a floating point number up to 16 decimal places.

Identity report conducted in the United Kingdom

The example in the code box shows an identity report conducted in the United Kingdom using the https://api.onfido.com/ base URL.

Sources (credit_agencies, voting_register, telephone_database) are displayed as breakdowns with their own result value.

Identity report conducted in the United States

The example in the code box shows the results for an Identity report conducted in the United States using the https://api.us.onfido.com/ base URL.

Any elements that are positively matched will be returned as clear in the report object breakdowns, including the source or sources of the database match in the properties field. When a match cannot be found (i.e. result is not clear) the corresponding properties bucket will be empty as such "properties":{}.

The report includes Social Security Number for a US applicant as an additional match under the ssn breakdown.

Identity report conducted outside of the UK/US

The example in the code box shows the results for an Identity report conducted in a jurisdiction other than the United Kingdom or United States using the https://api.onfido.com/ base URL, where sources are shown as comma separated under properties.

Identity Standard

This check should be used for employment or recruitment purposes, or where identity verification is performed in an unregulated industry.

Overall result logic:

• "result": "clear" at least one source matches the applicant's name and address
• "result": "consider" the name and date of birth is matched, but no name and address matches are found
• "result": "unidentified" no matches are found

When the SSN or the last four digits of the SSN are provided:

• "result": "clear" at least one source matches the applicant's name and address, and the last four digits of the SSN are matched
• "result": "unidentified" no matches are found
• "result": "consider" otherwise

Number of addresses: This check will attempt to find an address match for the current applicant address. If no match is found it will attempt to match the previous address (if provided), up to a total of 3 applicant addresses.

Mortality: Not checked.

Identity report custom logic

You can (optionally) build your own logic around report results.

For example, you may require matches to be found on 2 or more sources and at least 1 match on the applicant's name and current address.

In this example, you would add criteria of:

1. >=2 against total_number of sources under the total_sources sub-breakdown that is under the sources parent breakdown.

2. clear against the result value under the address parent breakdown.

Watchlist KYC report

A Watchlist KYC 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.

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 includes, but is not limited to: name and date of birth of match, aliases and associates, and relevant events and sources. Each event will correspond to a relevant category of list, which drives one of the breakdowns, and the overall result will be consider.

When available, URLs to data sources are provided, as well as pictures of the individual found in the match. This, along with other detail in the response, allows you to quickly assess the relevancy of the match and eliminate false positives.

Required applicant data

For Watchlist (KYC) reports, the following applicant data must be provided:

first_name

last_name

Recommended applicant data

dob

address[]postcode (ZIP code in US)

address[]country

address[]state (required 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 country is optional but recommended.

The applicant address object is nested inside the applicant object.

Results are filtered by country of operation or office, under these circumstances:

• There are PEP matches only
• There are PEP matches with Adverse Media

The country filter is not applied, or in other words, results will still appear regardless of the address country, under these circumstances:

• There are adverse media matches only
• Address does not have a country
• Sanctions, Money Laundering or Terrorist related events will always appear even if the country filter is applied

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 AML report

A Watchlist AML check 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. Fields include, but are not limited to: name of match, associates, date of birth, related keywords, type of list, name of list, and when the entry was last updated. When available, URLs to data sources are provided, as well as pictures of the individual found in the match.

Required applicant data

For Watchlist Full checks, the following applicant data must be provided:

first_name

last_name

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 Full report

A Watchlist Full check 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).

Required applicant data

For Watchlist Full checks, the following applicant data must be provided:

first_name

last_name

Recommended applicant data

dob

Extra report options

For Watchlist Full reports, you can use the options array when creating a check. You can populate this with the following:

• peps - returns politically_exposed_person breakdown matches only
• sanctions - returns sanction breakdown matches only

If no options are specified, all types will be searched: PEPs, Sanctions and Warnings.

Each match will be returned under records and includes, but is not limited to: name of match, associates, date of birth, related keywords, type of list, name of list, and when the entry was last updated. When available, URLs to data sources are provided, as well as pictures of the individual found in the match. This allows you to quickly assess the relevancy of the match and eliminate false positives.

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

Street Level report

A Street Level report confirms a person's address by sending a letter to their home with a unique verification code. The applicant enters this code online to confirm their address, which yeilds a "result": "clear". If after 15 days no response is received, the report will return a "result": "consider".

Required applicant data

For Street Level reports, the following applicant data must be provided:

first_name

last_name

address[]street

address[]postcode (ZIP code in US)

address[]country

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.

Delivery times

The time at which the 15 day counter starts depends on the check type. For Express checks, it starts from the report creation date. For Standard checks, time starts counting from the moment the applicant has submitted their details in the applicant form.

Letters to UK addresses are sent out by Royal Mail second class postal service. Letters to countries other than the UK are sent out by Royal Mail first class postal service.

All mail is collected Monday-Friday at 3:00pm UK time, excluding UK bank holidays. This means that letters for any reports created after 3pm on a Friday will only be collected on the following Monday at 3pm.

Delivery times from time of mail collection:

• UK: 2 to 3 working days, including Saturdays.
• Europe: 3 to 5 working days.
• Rest of the World: 5 to 7 working days.

Remote areas may take longer.

Royal Mail claim to have a 99% deliverability rate in the UK and 93% for Rest of the World. Providing good quality address data, with all fields correctly filled in the applicant object, greatly increases the deliverability of the letter. Do note that deliverability of the letter is not enough to clear the report. The applicant must enter the code online within the 15 days in order for the report to return as clear.

Customisation

The default letter is Onfido branded and directs the applicant to enter their code at https://onfido.com/slv.

Alternatively the letter can be customised with your branding of choice. If you wish to discuss this please contact your account manager or email client-support@onfido.com.

You can also build your own front end for the applicant to input their code using the submit code endpoint.

Street Level: Breakdowns

Proof of Address report

The document’s issuing country must be specified when uploading the document via the document upload endpoint by setting the issuing_country field. If the issuing_country field is not specified or is from an unsupported country (i.e. it is different from "GBR"), the document will be uploaded on the system however it will not be processed and the report will complete with the status set to cancelled and the result set to null.

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 three-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

Capture-only document types

For PoA documents from unsupported countries (i.e. non-UK PoA documents), the following document types can be uploaded to the system:

Proof of Address: Breakdowns

A PoA report upon completion is composed of 3 breakdowns.

Proof of Address: Properties

Data points extracted from PoA documents are returned in the properties attribute:

The summary period and the issue date are mutually exclusive, in the sense that only one of them is returned in the report properties attribute (either the summary period start and end dates or the issue date). Issue date may not be returned if document has only expiry date.

Overall result logic

The PoA report can return a result of clear or consider or null.

The overall report result will be clear if all of the following are true:

• the quality of the provided PoA document is sufficient to process it
• the provided PoA document is a supported UK PoA document
• the data provided by the applicant matches the data that is on their PoA document
• the source integrity of the provided PoA document is sufficient to process it

The overall report result will be null if any of the following is true:

• the issuing_country field set when uploading the document is from an unsupported country (i.e. it is different from "GBR")
• the issuing_country field is not provided when uploading the document

Please note that if the report result is null, the report status will be cancelled.

The overall report result will be consider if any of the following is true:

• the document was not of enough quality to be processed (e.g. image blurred, data points not visible on the document). In this scenario, the value of the image_quality breakdown (which is part of the image_integrity breakdown) will be unidentified and no data will be extracted from the document, hence the report properties attribute will be empty and all the other breakdowns will be null
• the document is not a valid UK PoA document (i.e. it does not feature in the list of supported document types). In this scenario the value of the supported_document breakdown (which is part of the document_classification breakdown) will be unidentified, no data will be extracted from the document, hence the report properties attribute will be empty and the data comparison breakdowns will be set to null
• the data provided by the applicant does not match the data extracted from the PoA document. In this scenario the breakdowns first_name, last_name and address (which are part of the data_comparison breakdown) will have a value of unidentified. Data is extracted from the document and returned as part of the report properties attribute.
• the document was digitally tampered and therefore the source integrity is insufficient for it to be processed. In this scenario, the value of the digitally_tampered breakdown (which is part of the source_integrity breakdown) will be consider

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.

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

Autofill

Autofill takes an uploaded document and returns information extracted from the document. This is a synchronous request, which means the extracted information will be presented immediately in the API response.

Request body parameters

Extraction result

If data has been successfully extracted, the API response will contain the properties document_classification and extracted_data.

document_classification has the following properties:

extracted_data has the following properties:

Extraction data will not be populated if the document is issued by a country subject to comprehensive US sanctions.

Classification failure

If the document cannot be recognised, a classification_failure will be returned.

Extraction failure

If no data can be extracted, an extraction_failure will be returned.

Report type group object

The report type group object defines the set of reports to be requested in a check.

Note that more than one report type group can be requested in a single check.

Check object

Check status