> ## Documentation Index
> Fetch the complete documentation index at: https://docs.idmetagroup.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Philippines TIN sandbox

> Predetermined API payloads to retrieve every Philippines TIN status in sandbox mode.

Sandbox payloads for the [Stateless TIN](https://docs.idmetagroup.com/stateless-verification-api/philippines-government/tin.md) endpoint.

```http theme={null}
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](https://docs.idmetagroup.com/stateless-verification-api/sandbox.md) for the full matching rules.

### Verified

> **VERIFIED — sample 1**
>
> **Request**
>
> ```json theme={null}
> {
>   "tin": "111111111",
>   "branchCode": "00000",
>   "firstName": "Juan",
>   "lastName": "Dela Cruz",
>   "genderDescription": "Male",
>   "birthDate": "1990-01-15"
> }
> ```
>
> **Response** — HTTP `200`
>
> ```json theme={null}
> {
>   "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**
>
> ```json theme={null}
> {
>   "tin": "222222222",
>   "branchCode": "00000",
>   "firstName": "Maria",
>   "middleName": "Lopez",
>   "lastName": "Reyes",
>   "genderDescription": "Female",
>   "birthDate": "1985-07-22"
> }
> ```
>
> **Response** — HTTP `200`
>
> ```json theme={null}
> {
>   "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**
>
> ```json theme={null}
> {
>   "tin": "999999999",
>   "branchCode": "00000",
>   "firstName": "Juan",
>   "lastName": "Dela Cruz",
>   "genderDescription": "Male",
>   "birthDate": "1990-01-15"
> }
> ```
>
> **Response** — HTTP `200`
>
> ```json theme={null}
> {
>   "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**
>
> ```json theme={null}
> {
>   "tin": "888888888",
>   "branchCode": "00000",
>   "firstName": "Maria",
>   "middleName": "Lopez",
>   "lastName": "Reyes",
>   "genderDescription": "Female",
>   "birthDate": "1985-07-22"
> }
> ```
>
> **Response** — HTTP `200`
>
> ```json theme={null}
> {
>   "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**
>
> ```json theme={null}
> {
>   "tin": "555555555",
>   "branchCode": "00000",
>   "firstName": "Juan",
>   "lastName": "Dela Cruz",
>   "genderDescription": "Male",
>   "birthDate": "1990-01-15"
> }
> ```
>
> **Response** — HTTP `200`
>
> ```json theme={null}
> {
>   "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**
>
> ```json theme={null}
> {
>   "tin": "12345",
>   "branchCode": "00000",
>   "firstName": "Juan",
>   "lastName": "Dela Cruz",
>   "genderDescription": "Male",
>   "birthDate": "1990-01-15"
> }
> ```
>
> **Response** — HTTP `400`
>
> ```json theme={null}
> {
>   "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**
>
> ```json theme={null}
> {
>   "tin": "111111111",
>   "branchCode": "00000",
>   "firstName": "Juan",
>   "lastName": "Dela Cruz",
>   "genderDescription": "M",
>   "birthDate": "1990-01-15"
> }
> ```
>
> **Response** — HTTP `400`
>
> ```json theme={null}
> {
>   "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**
>
> ```json theme={null}
> {
>   "tin": "111111111",
>   "branchCode": "00000",
>   "firstName": "Juan",
>   "lastName": "Dela Cruz",
>   "genderDescription": "Male",
>   "birthDate": "15/01/1990"
> }
> ```
>
> **Response** — HTTP `400`
>
> ```json theme={null}
> {
>   "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**
>
> ```json theme={null}
> {
>   "tin": "111111111",
>   "branchCode": "00000",
>   "firstName": "Juan",
>   "lastName": "Dela Cruz",
>   "genderDescription": "Male",
>   "birthDate": "1990-01-15",
>   "trustFlowId": "anything"
> }
> ```
>
> **Response** — HTTP `400`
>
> ```json theme={null}
> {
>   "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>"
> }
> ```
>
> > [!WARNING]
> >
> > `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**
>
> ```json theme={null}
> {
>   "tin": "000000000",
>   "branchCode": "00000",
>   "firstName": "Juan",
>   "lastName": "Dela Cruz",
>   "genderDescription": "Male",
>   "birthDate": "1990-01-15"
> }
> ```
>
> **Response** — HTTP `500`
>
> ```json theme={null}
> {
>   "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**
>
> ```json theme={null}
> {
>   "tin": "000000001",
>   "branchCode": "00000",
>   "firstName": "Maria",
>   "middleName": "Lopez",
>   "lastName": "Reyes",
>   "genderDescription": "Female",
>   "birthDate": "1985-07-22"
> }
> ```
>
> **Response** — HTTP `500`
>
> ```json theme={null}
> {
>   "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](https://docs.idmetagroup.com/stateless-verification-api/sandbox.md#non-verification-responses) for their envelopes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.