Run a Visa check (API)

This developer guide takes you through the steps to run a Visa check with the PassFort API 4.0 to confirm whether an individual has the right to work or study.

1. Select a profile for the check

Visa checks are always run on profiles with the INDIVIDUAL entity type.

Choose an individual profile to run the check on, and get the profile’s ID (e.g. 3ed203ae-cade-11e7-a6a9-000000000000).

If you haven’t created the profile yet, follow these steps to create an individual profile via the API.
You can also create a profile via the portal. To get the profile ID (used to run the check in the next step), view the profile in the portal and copy the string of letters and numbers displayed after /onboarding/ in the URL.

2. Confirm the profile has the required task and fields

To see the profile’s data, make a request to the endpoint below.

Request endpoint:

GET https://api.passfort.com/4.0/profiles/{profile_id}

Sample response:

{
"applications": [...],
"category": "CUSTOMER",
"checks": [...],
"collected_data": {
"address_history": [
{
"address": {
"country": "AUS",
"original_freeform_address": "10, SW1A 2AA",
"original_structured_address": {
"country": "AUS",
"postal_code": "SW1A 2AA",
"street_number": "10"
},
"postal_code": "SW1A 2AA",
"street_number": "10",
"type": "STRUCTURED"
}
}
],
"entity_type": "INDIVIDUAL",
"personal_details": {
"dob": "1950-01-01",
"name": {
"family_name": "Smith",
"given_names": [
"Thomas",
"James"
]
},
"nationality": "GBR"
}
},
"collection_steps": [],
"creation_date": "2019-04-25 14:45:49",
"display_name": "Thomas James Smith",
"document_images": [],
"events": [],
"has_associates": false,
"has_collection_steps": false,
"id": "d12896b8-6768-11e9-beed-0a580a0006c9",
"linked_to": [],
"role": "INDIVIDUAL_CUSTOMER",
"root_id": "d12896b8-6768-11e9-beed-0a580a0006c9",
"status": "NORMAL",
"tags": [],
"task_progress": { ... },
"task_types": [ ... ],
"tasks": [
{
"check_ids": [],
"creation_date": "2019-04-25 16:10:59",
"id": "b6acd5e6-6774-11e9-80c1-0a580a000026",
"is_complete": false,
"is_expired": false,
"is_skipped": false,
"state": "INCOMPLETE",
"type": "INDIVIDUAL_VERIFY_IMMIGRATION_STATUS",
"variant": { ... }
},
{ ... },
{ ... },
{ ... },
{ ... }
],
"unresolved_event_types": [],
"verified_data": {
"entity_type": "INDIVIDUAL"
}
}

Use the response to:

  1. Confirm the profile has a task with the type set to INDIVIDUAL_VERIFY_IMMIGRATION_STATUS.
  2. Take note of the value in the Verify immigration status task’s id. You’ll need it for the next step.
  3. Confirm the profile has the following data for collected_data.personal_details object:
    1. At least one string for the personal_details.name.given_names array. This array of string contains the individual’s first & middle names.
    2. A string for the personal_details.name.family_name field. This string contains the individual’s surname.
    3. A string for the personal_details.dob field. This string contains a partial date, recording a year and possibly month and day. Date will be in one of three formats: YYYY, YYYY-MM, YYYY-MM-DD.
  4. Confirm the profile has the following data for the most recent address string in the collected_data.address_history array:
    1. address.country must have the value AUS. This signifies that the individual’s current country of residence is Australia.

If the keys above do not exist or do not contain valid data, the check will return an error when you try to run it in step 3.

To learn how to update the profile’s collected_data, see Update PassFort's profile data.

3. Run the check

To run the check, make a request to the endpoint below.

Request endpoint:

POST https://api.passfort.com/4.0/profiles/{profile_id}/checks

Body parameters:

When you make the POST request, include the following parameters in the body.

Key

Value

Description

check_type

Required

String

VISA_CHECK

The type of check that’s being run.

document_metadata

Required

Object

For a sample value, see the sample request body below.

The document object.

document_metadata.document_type

Required

String

PASSPORT

For the Visa check, the document type always a passport.

document_metadata.number

Required

String

Sample value: 084762392

The individual’s passport number.

document_metadata.country_code

Required

String

Sample value: GBR

The country must be provided as an ISO3 code.

The country that issued individual’s passport.

Sample request body:

{
"check_type": "VISA_CHECK",
"document_metadata": {
"document_type": "PASSPORT",
"number": "084762392",
"country_code": "GBR"
},
"task_ids": [
"428ec152-677b-11e9-8f11-0a580a00002b"
]
}

Sample response:

{
"check_type": "VISA_CHECK",
"completed_on": "2019-04-29 11:00:45",
"document_metadata": {
"country_code": "GBR",
"document_type": "PASSPORT",
"number": "xxxxxxxx"
},
"errors": [],
"id": "096b9d66-6a6e-11e9-840a-0a580a001814",
"input_data": { ... },
"instructed_on": "2019-04-29 11:00:44",
"output_data": {
"entity_type": "INDIVIDUAL",
"visa_check": {
"failure_reason": "",
"visas": [
{
"country_code": "AUS",
"details": [
{
"name": "Study Condition",
"value": "No limitations on study."
},
{
"name": "Visa Applicant",
"value": "Primary"
},
{
"name": "Visa Class",
"value": "SI"
},
{
"name": "Visa Type",
"value": "457"
},
{
"name": "Visa Type Details",
"value": "For people sponsored by an employer previously named Business (Long Stay)"
}
],
"entitlement": "STUDY",
"expiry_date": "2030-10-22",
"field_checks": [ ... ],
"grant_date": "2000-10-22",
"holder": { ... },
"name": "Temporary Work (Skilled)"
}
]
}
},
"performed_on": "2019-04-29 11:00:45",
"providers": [ ... ],
"result": "Pass",
"started_on": "2019-04-29 11:00:45",
"state": "COMPLETE",
"task_ids": [
"428ec152-677b-11e9-8f11-0a580a00002b"
],
"variant": { ... }
}

Use the response to:

  1. Confirm the check passed. If it has, the value of the result key is Pass.

    If the check hasn’t, the value of the result is Failed. The output_data.visa_check.failure_reason key contains details about why the check failed.

    If the data provider failed the check, the visas.field_checks key is not created and the visas array is empty.

    If the check failed because of the visa fields, any fields that failed during the check will have the CHECK_INVALID result in the visas.field_checks array. These are the fields that may fail and why:

    Field

    What causes the field to return CHECK_INVALID

    FIELD_ISSUED

    The visa grant date is in the future.

    FIELD_EXPIRY

    The visa expiry date is in the past.

    FIELD_GIVEN_NAMES

    The profile’s given name(s) do not match the name on the visa.

    FIELD_FAMILY_NAME

    The profile’s family name does not match the name on the visa.

    FIELD_DOB

    The profile’s date of birth does not match the date of birth on the visa.

  2. If the check has passed, see the visas.entitlement key to learn the type of entitlement the visa offers (e.g. work or study).
  3. If the check passed, see the visas.details key to learn details about the visa, including the visa class, visa type, and any work/study limitations.
Now that you have the results of the check, you may want to mark the task as complete.


How did we do?


Powered by HelpDocs