Validate a citizenship certificate

POST /api/v2/dvs/citizenship operationId: dvs.citizenship

Live: https://gdapi.globaldata.net.au/api/v2/dvs/citizenship · Sandbox: https://sandbox-gdapi.globaldata.net.au/api/v2/dvs/citizenship

Validates a Citizenship certificate against the Australian Document Verification Service (DVS).

Sandbox environment

When simulating queries in the sandbox environment, a specific set of citizenship certificates will return a specific result. The response will be determined by the stock number:

DVS sandbox responses for this document

Request body

Content type application/json. The citizenship certificate details to validate

Field	Description
`preflight`	boolean When set to true, the request will only perform a preflight check to validate the input parameters. No actual verification will be performed. Example: `false`
`consent`	boolean The individual's consent to perform the check Example: `true`
`first_name`	string The first name of the document holder Example: `John`
`last_name`	string The last name of the document holder Example: `Smith`
`birth_date`	string (date) The date of birth of the document holder Example: `1980-01-01`
`acquisition_date`	string (date) The acquisition date specified on the certificate Example: `1980-01-01`
`stock_number`	string The stock number specified on the certificate Example: `123/45678`

Responses

200

Result of the document verification check

application/json

Field	Description
`message`	string A message indicating the result of the request. This will be `Ok` if the request was successful. Example: `Ok`
`function`	string The function that was called Example: `dvs_citizenship`
`api_reference`	string (uuid) A unique identifier for this request. This can be used to track the request in the logs. Example: `fe4291ca-d831-4760-96df-c9cb03b3cd95`
`data`	object The check data
`data.response_type`	string The type of response Example: `CitizenshipCertificateResponse`
`data.activity_id`	string A reference ID for this activity. This ID can be used to track the activity in the logs. Example: `sandbox-d06ed58a-b279-4f50-9b6e-5a0a26b4e87d`
`data.verification_request_number`	string A unique reference number for this request Example: `dec306ed-7cff-41c0-b02f-889e430f5309`
`data.verification_result_code`	string The result of the verification `Y` - The document is valid `N` - The document was not matched `D` - The document is invalid or not electronically captured `S` - An error occurred during the check Enum: `Y`, `N`, `S`, `D` Example: `N`
`data.additional_information`	array of objects An array of expanded responses returned from the DVSHub or Document Issuer for N or D results
`data.additional_information[].message`	string A message indicating the reason for the N or D result. Example: `Document invalid.`
`data.additional_information[].code`	string A code number associated with the corresponding message. Example: `CC-001`

202

A successful preflight check. A 400 will be returned if the preflight check fails.

application/json

Field	Description
`message`	string A message indicating the result of the request. This will be `Ok` if the request was successful. Example: `Ok`
`function`	string The function that was called Example: `dvs_aec`
`api_reference`	string (uuid) A unique identifier for this request. This can be used to track the request in the logs. Example: `fe4291ca-d831-4760-96df-c9cb03b3cd95`
`data`	null For preflight checks this is null

Standard error responses: 400 401 402 403 429 503 5XX See common error responses

Previous Validate a Centrelink concession card Next Validate a death certificate

Request body application/json

{
    "preflight": false,
    "consent": true,
    "first_name": "John",
    "last_name": "Smith",
    "birth_date": "1980-01-01",
    "acquisition_date": "1980-01-01",
    "stock_number": "123/45678"
}

Response

200 Result of the document verification check

{
    "message": "Ok",
    "function": "dvs_citizenship",
    "api_reference": "fe4291ca-d831-4760-96df-c9cb03b3cd95",
    "data": {
        "response_type": "CitizenshipCertificateResponse",
        "activity_id": "sandbox-d06ed58a-b279-4f50-9b6e-5a0a26b4e87d",
        "verification_request_number": "dec306ed-7cff-41c0-b02f-889e430f5309",
        "verification_result_code": "N",
        "additional_information": [
            {
                "message": "Document invalid.",
                "code": "CC-001"
            }
        ]
    }
}

202 A successful preflight check. A 400 will be returned if the preflight check fails.

{
    "message": "Ok",
    "function": "dvs_aec",
    "api_reference": "fe4291ca-d831-4760-96df-c9cb03b3cd95",
    "data": null
}

400 Bad or missing input parameter shared error response

{
    "message": "string"
}

401 Unauthorized - The request is not authorized. shared error response

{
    "message": "API Key Inactive"
}

402 Insufficient Credit - Insufficient credit to process this request shared error response

{
    "message": "Insufficient Credit"
}

403 No access - No permission to process this request shared error response

{
    "message": "No access"
}

429 Rate limited - The request rate limit has been reached shared error response

{
    "message": "Rate limited"
}

503 DVS Service is unavailable. This is returned if the DVS returns a System Error result. The request was not successful and should be retried later. shared error response

{
    "message": "DVS returned a system error. Please try again later."
}

5XX Internal error - Internal system error shared error response

{
    "message": "Internal error"
}