All categories > Developer documentation > Guide to running a Visa check

Guide to running a Visa check

Updated 2 weeks ago by Ainsley

1. Select a profile for the check
2. Confirm the profile has the required task and fields
3. Run the check
4. Mark the task complete
- Complete the task as passed
- Complete the task as failed

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.

Learn more about Visa checks.

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 number (e.g. 3ed203ae-cade-11e7-a6a9-000000000000).

If you haven’t created the profile yet, follow these steps to create an individual profile.

2. Confirm the profile has the required task and fields

To see the profile’s data, make the following request:

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

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:

Confirm the profile has a task with the type set to INDIVIDUAL_VERIFY_IMMIGRATION_STATUS.
Take note of the value in the Verify immigration status task’s id. You’ll need it for the next step.
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.
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 collected_data fields 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 Extension A: Updating the profile.

3. Run the check

To run the check, make the following request:

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

Data for the request body:

When you make the request, complete the following data.

Name of field, object, or object data	Description	Type	Notes
`check_type`	The type of check that’s being run.	String	Required. Value must be `VISA_CHECK` for the Visa check to run.
`document_metadata`	The document object.	Object	Required.
`document_metadata.document_type`	Field of the `document_metadata` object that contains the type of document that will be searched in the data provider’s database. For the Visa check, the document type always a passport.	String	Required. Value must be `PASSPORT` for the Visa check to pass.
`document_metadata.number`	Field of the `document_metadata` object that contains the document number. For the Visa check, this is the individual’s passport number.	String	Required.
`document_metadata.country_code`	Field of the `document_metadata` object that contains the document country. For the Visa check, this is the individual’s passport issuing country.	String	Required. The country is provided as an ISO3 code. Learn more.

Request body:

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

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:

Confirm the check passed. If it has, the result is set to Pass.

If the check hasn’t, the result is set to Failed and details about why the check failed are added to output_data.visa_check.failure_reason.

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

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

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.

If the check passed, see what kind of entitlement the visa offers (e.g. work or study). The visa entitlement is contained in visas.entitlement.
If the check passed, see the details of the visa, including the visa class, visa type, and any work/study limitations. This information is contained in the fields under visas.details.

4. Mark the task complete

If you’ve configured your smart policy to mark the task complete automatically when the check passes, you don’t need to follow this step.

When a task is complete, it’s either completed as passed or failed.

Complete the task as passed when the profile meets all requirements of the check (e.g. the check result is Pass).

Complete the task as failed when the profile does not meet the requirements (e.g. the check result returned Failed three times).

Complete the task as passed

Make the following request to complete the task as passed:

POST https://api.passfort.com/4.0/profiles/:profile_id/tasks/:task_id

Request :

{
   "state": "COMPLETED_PASS"
}

Response :

{
    "check_ids": [
        "096d44f8-6a8f-11e9-96fd-0a580a00181b",
        "835aee22-6a8e-11e9-b586-0a580a000743"
    ],
    "creation_date": "2019-04-29 14:51:45",
    "id": "4edfe68c-6a8e-11e9-afb9-0a580a00003d",
    "is_complete": true,
    "is_expired": false,
    "is_skipped": false,
    "state": "COMPLETED_PASS",
    "type": "INDIVIDUAL_VERIFY_IMMIGRATION_STATUS",
    "variant": {
        "id": "0c122aa4-6a7b-11e9-8583-0a580a0006d7",
        "name": "Immigration status - Work AND study",
        "task_type": "INDIVIDUAL_VERIFY_IMMIGRATION_STATUS"
    }
}

When all tasks are completed as passed, the profile’s application can be approved. Learn about approving a profile application.

The state field replaces the old is_complete field that used to be part of this request. Making the state field equal to COMPLETED_PASS is the same behaviour as making the old is_complete field equal to true.

Complete the task as failed

Make the following request to complete the task as failed:

POST https://api.passfort.com/4.0/profiles/:profile_id/tasks/:task_id