Run a Visa check using the 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.
Choose a profile and get the profile ID
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, for example, 3ed203ae-cade-11e7-a6a9-000000000000
.
If you haven't created the profile yet, follow the steps to create a profile using the API. You can also create a profile via the portal. To get the profile ID, used to run the check in the following section, view the profile in the portal and copy the string of letters and numbers displayed after /onboarding/
in the URL.
Confirm the profile has the required fields for the check
To see all data on the profile, make a request to the following endpoint.
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:
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. If there is more than one task with the same alias (which happens when a task has more than one version), use the task with"is_expired": "false"
.Confirm the profile has the following data for
collected_data.personal_details
object:At least one string for the
personal_details.name.given_names
array. This array of string contains the individual’s first & middle names.A string for the
personal_details.name.family_name
field. This string contains the individual’s surname.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 thecollected_data.address_history
array:address.country
must have the valueAUS
. This signifies that the individual’s current country of residence is Australia.
If these keys do not exist or do not contain valid data, the check will return an error when you try to run it in the next section.
To learn how to add/update the fields in the profile's collected_data
, see Updated Passfort's profile data.
Run the check
To run the check, send a request to the following endpoint.
Request endpoint:
POST https://api.passfort.com/4.0/profiles/{profile_id}/checks
By default, the Visa check runs synchronously. You can also send mode
as a query parameter to run the check asynchronously.
Body parameters:
When you make the POST
request, include the following parameters in the body.
Key | Value | Description |
*Required string |
| The check type. |
*Required object | For a sample value, see the following sample request body. | The document object. |
*Required string |
| For the Visa check, the document type is always a passport. |
*Required string | Sample value: | The individual’s passport number. |
*Required string | Sample value: The country must be provided as an ISO3 code. | The country that issued individual’s passport. |
*Required object | For a sample value, see the following sample request body. | Object to indicate which variant of the check will run. |
*Required string This key is optional if | Sample value:
| The check alias. |
*Required string This key is optional if | Sample value:
| The unique identifier for the check. |
Sample request body:
{ "check_type": "VISA_CHECK", "documents_metadata": [ { "document_type": "PASSPORT", "number": "084762392", "country_code": "GBR" } ], "task_ids": [ "428ec152-677b-11e9-8f11-0a580a00002b" ], "variant": { "alias": "default" } }
Sample response:
{ "check_type": "VISA_CHECK", "completed_on": "2019-04-29 11:00:45", "documents_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 value of the
result
key isPass
.If the check hasn’t, the value of the
result
isFailed
. Theoutput_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 thevisas
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 thevisas.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.
If the check has passed, see the
visas.entitlement
key to learn the type of entitlement the visa offers (e.g. work or study).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.