Validate a marriage certificate

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

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

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

The registration field is state-specific: for QLD the registration_date is used, while for all other states the registration_number is used. If you supply the field that does not apply to the requested state, it is silently ignored and not forwarded to DVS. A supplied registration_date must still be a valid YYYY-MM-DD date even when it will be ignored, otherwise the request is rejected.

Sandbox environment

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

DVS sandbox responses for this document

Request body

Content type application/json. The marriage 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`
`oac`	string [4..20 characters] or null The DVS Identity (Originating Agency Code) to run the check under. You only need this if Global Data has set up additional DVS Identities on your account, for example because you submit checks on behalf of other organisations. If you leave it out, your account's own DVS Identity is used. If you send it, it must be your account's own DVS Identity or one of its additional identities. Any other value is rejected. In the sandbox you can also use the sample identities `SANDBOX1`, `SANDBOX2` and `SANDBOX3`, so you can try checks on behalf of another organisation before your own are set up. They are rejected in the live environment. Example: `ABC1`
`first_name1`	string The first name of the first person listed on the document Example: `John`
`last_name1`	string The last name of the first person listed on the document Example: `Smith`
`first_name2`	string The first name of the second person listed on the document Example: `Mary`
`last_name2`	string The last name of the second person listed on the document Example: `Jones`
`event_date`	string (date) The date of the marriage Example: `1980-01-01`
`registration_number`	string The registration number on the certificate to be validated. Used for all states except QLD; silently ignored for QLD certificates. Example: `1234567`
`certificate_number`	string The certificate number on the certificate to be validated Example: `123456789`
`registration_date`	string (date) The registration date on the certificate to be validated. Used for QLD certificates only; silently ignored for all other states. Must be a valid YYYY-MM-DD date even when ignored. Example: `2021-02-28`
`state`	string The state of issue for the marriage certificate Enum: `NSW`, `VIC`, `QLD`, `TAS`, `ACT`, `NT`, `SA`, `WA` Example: `VIC`

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_marriage`
`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: `MarriageCertificateResponse`
`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: `Family Name does not match.`
`data.additional_information[].code`	string A code number associated with the corresponding message. Example: `MC-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 an ImmiCard Next Validate a Medicare card

Request body application/json

{
    "preflight": false,
    "consent": true,
    "oac": "ABC1",
    "first_name1": "John",
    "last_name1": "Smith",
    "first_name2": "Mary",
    "last_name2": "Jones",
    "event_date": "1980-01-01",
    "registration_number": "1234567",
    "certificate_number": "123456789",
    "registration_date": "2021-02-28",
    "state": "VIC"
}

Response

200 Result of the document verification check

{
    "message": "Ok",
    "function": "dvs_marriage",
    "api_reference": "fe4291ca-d831-4760-96df-c9cb03b3cd95",
    "data": {
        "response_type": "MarriageCertificateResponse",
        "activity_id": "sandbox-d06ed58a-b279-4f50-9b6e-5a0a26b4e87d",
        "verification_request_number": "dec306ed-7cff-41c0-b02f-889e430f5309",
        "verification_result_code": "N",
        "additional_information": [
            {
                "message": "Family Name does not match.",
                "code": "MC-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"
}