Philippines TIN sandbox

Sandbox payloads for the Stateless TIN endpoint.

POST /api/v3/verifications/philippines/tin-passthrough

When your account is in sandbox mode, these payloads return the outcomes shown below. Any other valid payload is answered as a no-match — HTTP 200 with isValid set to false. Values are case-sensitive. transactionId and createdAt are generated per request, and metadata is echoed back from your request. See Sandbox introduction for the full matching rules.

Verified

VERIFIED — sample 1

Request

{
  "tin": "111111111",
  "branchCode": "00000",
  "firstName": "Juan",
  "lastName": "Dela Cruz",
  "genderDescription": "Male",
  "birthDate": "1990-01-15"
}

Response — HTTP 200

{
  "success": true,
  "message": "Philippines TIN processed successfully",
  "data": {
    "code": 0,
    "message": "TIN is valid",
    "isValid": true
  },
  "verificationStatus": "VERIFIED",
  "verificationStatusCode": 3,
  "transactionId": "<uuid generated per request>",
  "verificationType": "philippines_tin",
  "createdAt": "<UTC timestamp of the request>"
}

VERIFIED — sample 2, with middle name

Request

{
  "tin": "222222222",
  "branchCode": "00000",
  "firstName": "Maria",
  "middleName": "Lopez",
  "lastName": "Reyes",
  "genderDescription": "Female",
  "birthDate": "1985-07-22"
}

Response — HTTP 200

{
  "success": true,
  "message": "Philippines TIN processed successfully",
  "data": {
    "code": 0,
    "message": "TIN is valid",
    "isValid": true
  },
  "verificationStatus": "VERIFIED",
  "verificationStatusCode": 3,
  "transactionId": "<uuid generated per request>",
  "verificationType": "philippines_tin",
  "createdAt": "<UTC timestamp of the request>"
}

Rejected

A rejection is a completed verification, not an error: success is true and HTTP status is 200. In live mode a rejection is billed.

REJECTED — sample 1

Request

{
  "tin": "999999999",
  "branchCode": "00000",
  "firstName": "Juan",
  "lastName": "Dela Cruz",
  "genderDescription": "Male",
  "birthDate": "1990-01-15"
}

Response — HTTP 200

{
  "success": true,
  "message": "Philippines TIN processed successfully",
  "data": {
    "code": 1,
    "message": "TIN could not be verified.",
    "isValid": false
  },
  "verificationStatus": "REJECTED",
  "verificationStatusCode": 1,
  "transactionId": "<uuid generated per request>",
  "verificationType": "philippines_tin",
  "createdAt": "<UTC timestamp of the request>"
}

REJECTED — sample 2, with middle name

Request

{
  "tin": "888888888",
  "branchCode": "00000",
  "firstName": "Maria",
  "middleName": "Lopez",
  "lastName": "Reyes",
  "genderDescription": "Female",
  "birthDate": "1985-07-22"
}

Response — HTTP 200

{
  "success": true,
  "message": "Philippines TIN processed successfully",
  "data": {
    "code": 1,
    "message": "TIN could not be verified.",
    "isValid": false
  },
  "verificationStatus": "REJECTED",
  "verificationStatusCode": 1,
  "transactionId": "<uuid generated per request>",
  "verificationType": "philippines_tin",
  "createdAt": "<UTC timestamp of the request>"
}

REJECTED — Not verified, unmatched payload fallback

Request

{
  "tin": "555555555",
  "branchCode": "00000",
  "firstName": "Juan",
  "lastName": "Dela Cruz",
  "genderDescription": "Male",
  "birthDate": "1990-01-15"
}

Response — HTTP 200

{
  "success": true,
  "message": "Philippines TIN processed successfully",
  "data": {
    "code": 1,
    "isValid": false
  },
  "verificationStatus": "REJECTED",
  "verificationStatusCode": 1,
  "transactionId": "<uuid generated per request>",
  "verificationType": "philippines_tin",
  "createdAt": "<UTC timestamp of the request>"
}

This payload matches no documented scenario, so it takes the no-match fallback. Unlike the documented rejections, the fallback carries no data.message. Fire it once to confirm that an unknown TIN never reaches the live BIR source.

Validation failures

All validation failures return HTTP 400 with code set to VALIDATION_FAILED and the same message; only errors differs. Validation runs before any fixture matching, so these behave identically in sandbox and live. transactionId is null and no transaction row is written.

VALIDATION_FAILED — TIN not 9 digits

Request

{
  "tin": "12345",
  "branchCode": "00000",
  "firstName": "Juan",
  "lastName": "Dela Cruz",
  "genderDescription": "Male",
  "birthDate": "1990-01-15"
}

Response — HTTP 400

{
  "success": false,
  "code": "VALIDATION_FAILED",
  "message": "The request could not be validated. Please check the submitted fields.",
  "errors": {
    "tin": ["The tin field must be 9 digits."]
  },
  "transactionId": null,
  "verificationType": "philippines_tin",
  "createdAt": "<UTC timestamp of the request>"
}

tin must be exactly 9 digits and branchCode exactly 5 digits.

VALIDATION_FAILED — Gender not supported

Request

{
  "tin": "111111111",
  "branchCode": "00000",
  "firstName": "Juan",
  "lastName": "Dela Cruz",
  "genderDescription": "M",
  "birthDate": "1990-01-15"
}

Response — HTTP 400

{
  "success": false,
  "code": "VALIDATION_FAILED",
  "message": "The request could not be validated. Please check the submitted fields.",
  "errors": {
    "genderDescription": ["The selected gender description is invalid."]
  },
  "transactionId": null,
  "verificationType": "philippines_tin",
  "createdAt": "<UTC timestamp of the request>"
}

genderDescription accepts Male, Female, male or female.

VALIDATION_FAILED — Birth date in the wrong format

Request

{
  "tin": "111111111",
  "branchCode": "00000",
  "firstName": "Juan",
  "lastName": "Dela Cruz",
  "genderDescription": "Male",
  "birthDate": "15/01/1990"
}

Response — HTTP 400

{
  "success": false,
  "code": "VALIDATION_FAILED",
  "message": "The request could not be validated. Please check the submitted fields.",
  "errors": {
    "birthDate": ["The birth date field must match the format Y-m-d."]
  },
  "transactionId": null,
  "verificationType": "philippines_tin",
  "createdAt": "<UTC timestamp of the request>"
}

VALIDATION_FAILED — Trust flow fields sent to a stateless endpoint

Request

{
  "tin": "111111111",
  "branchCode": "00000",
  "firstName": "Juan",
  "lastName": "Dela Cruz",
  "genderDescription": "Male",
  "birthDate": "1990-01-15",
  "trustFlowId": "anything"
}

Response — HTTP 400

{
  "success": false,
  "code": "VALIDATION_FAILED",
  "message": "The request could not be validated. Please check the submitted fields.",
  "errors": {
    "trustFlowId": ["The trust flow id field is prohibited."]
  },
  "transactionId": null,
  "verificationType": "philippines_tin",
  "createdAt": "<UTC timestamp of the request>"
}

trustFlowId and trustValidationId are prohibited on stateless endpoints. Sending either is a validation failure, not a silently ignored field.

Source unavailable

FAILED — BIR source unavailable, sample 1

Request

{
  "tin": "000000000",
  "branchCode": "00000",
  "firstName": "Juan",
  "lastName": "Dela Cruz",
  "genderDescription": "Male",
  "birthDate": "1990-01-15"
}

Response — HTTP 500

{
  "success": false,
  "code": "PH_GOV_UNAVAILABLE",
  "message": "The Philippine government source is currently unavailable. Please try again later.",
  "verificationStatus": "FAILED",
  "verificationStatusCode": 6,
  "transactionId": "<uuid generated per request>",
  "verificationType": "philippines_tin",
  "createdAt": "<UTC timestamp of the request>"
}

There is no data key at all. The envelope treats code and data as mutually exclusive, so a coded failure drops data rather than emitting an empty object. Branch on code, not on the presence of data.

FAILED — BIR source unavailable, sample 2

Request

{
  "tin": "000000001",
  "branchCode": "00000",
  "firstName": "Maria",
  "middleName": "Lopez",
  "lastName": "Reyes",
  "genderDescription": "Female",
  "birthDate": "1985-07-22"
}

Response — HTTP 500

{
  "success": false,
  "code": "PH_GOV_UNAVAILABLE",
  "message": "The Philippine government source is currently unavailable. Please try again later.",
  "verificationStatus": "FAILED",
  "verificationStatusCode": 6,
  "transactionId": "<uuid generated per request>",
  "verificationType": "philippines_tin",
  "createdAt": "<UTC timestamp of the request>"
}

Account-level responses

Two further responses are not specific to this endpoint. A missing or invalid Authorization header returns HTTP 401, and an account without the philippines_tin plan returns HTTP 403 — both enforced in sandbox exactly as in live. See Sandbox introduction for their envelopes.

Stateless API Sandbox

Australia DVS

Philippines Government

Document OCR

Verified

Rejected

Validation failures

Source unavailable

Account-level responses

​Verified

​Rejected

​Validation failures

​Source unavailable

​Account-level responses

Verified

Rejected

Validation failures

Source unavailable

Account-level responses