---
updatedAt: 2026-07-13T07:05:39.000Z
agentTools:
  projectIndex: https://docs.getsmileapi.com/llms.txt
---

# Request Verification

## Request a Verification object.

This endpoint requires `consent` and the identity information to verify.
Place `idType`, `idSubType`, and `idNumber` in `additionalData.ids`. The
Sandbox field `dateOfBirth` maps to `additionalData.dob`, and `gender` maps to
`additionalData.gender`.

### Supported Sandbox ID Types

| ID Type         | Available Test Fields                                                                            |
|-----------------|--------------------------------------------------------------------------------------------------|
| `tin_ph`        | `fullName`, `firstName`, `middleName`, `lastName`, `suffix`, `idNumber`, `gender`, `dateOfBirth` |
| `pagibig_ph`    | `fullName`, `idNumber`                                                                           |
| `prclicense_ph` | `fullName`, `idSubType`, `idNumber`, `dateOfBirth`                                               |
| `nbi_ph`        | `fullName`, `idNumber`                                                                           |

### Sandbox Test Values

| ID Type         | Parameter     | Value                            |
|-----------------|---------------|----------------------------------|
| `tin_ph`        | `idType`      | `tin_ph`                         |
| `tin_ph`        | `fullName`    | `George Cimafranca Palomero Jr.` |
| `tin_ph`        | `firstName`   | `George`                         |
| `tin_ph`        | `middleName`  | `Cimafranca`                     |
| `tin_ph`        | `lastName`    | `Palomero`                       |
| `tin_ph`        | `suffix`      | `Jr.`                            |
| `tin_ph`        | `idNumber`    | `123456789`                      |
| `tin_ph`        | `gender`      | `Male`                           |
| `tin_ph`        | `dateOfBirth` | `1970-08-24`                     |
| `pagibig_ph`    | `idType`      | `pagibig_ph`                     |
| `pagibig_ph`    | `fullName`    | `George Cimafranca Palomero Jr.` |
| `pagibig_ph`    | `idNumber`    | `123456789012`                   |
| `prclicense_ph` | `idType`      | `prclicense_ph`                  |
| `prclicense_ph` | `fullName`    | `George Cimafranca Palomero Jr.` |
| `prclicense_ph` | `idSubType`   | `CRIMINOLOGIST`                  |
| `prclicense_ph` | `idNumber`    | `0123456`                        |
| `prclicense_ph` | `dateOfBirth` | `1970-08-24`                     |
| `nbi_ph`        | `idType`      | `nbi_ph`                         |
| `nbi_ph`        | `fullName`    | `George Cimafranca Palomero Jr.` |
| `nbi_ph`        | `idNumber`    | `ABC123DEF4-56GHI789J`           |

Use one Sandbox record per Verification request. For inputs outside these test
values, the Sandbox may not return a matched verification result.


# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Smile API",
    "version": "1.14.0",
    "description": "The Smile API provides employment and income data from a single API. ",
    "contact": {
      "name": "Smile Technology Pte Ltd",
      "url": "https://www.getsmileapi.com",
      "email": "info@getsmileapi.com"
    },
    "termsOfService": "https://www.getsmileapi.com/terms-and-conditions"
  },
  "servers": [
    {
      "url": "https://sandbox.smileapi.io/v1",
      "description": "Sandbox"
    },
    {
      "url": "https://open.smileapi.io/v1",
      "description": "Production"
    }
  ],
  "paths": {
    "/alpha/verifications": {
      "post": {
        "summary": "Request Verification",
        "description": "## Request a Verification object.\n\nThis endpoint requires `consent` and the identity information to verify.\nPlace `idType`, `idSubType`, and `idNumber` in `additionalData.ids`. The\nSandbox field `dateOfBirth` maps to `additionalData.dob`, and `gender` maps to\n`additionalData.gender`.\n\n### Supported Sandbox ID Types\n\n| ID Type         | Available Test Fields                                                                            |\n|-----------------|--------------------------------------------------------------------------------------------------|\n| `tin_ph`        | `fullName`, `firstName`, `middleName`, `lastName`, `suffix`, `idNumber`, `gender`, `dateOfBirth` |\n| `pagibig_ph`    | `fullName`, `idNumber`                                                                           |\n| `prclicense_ph` | `fullName`, `idSubType`, `idNumber`, `dateOfBirth`                                               |\n| `nbi_ph`        | `fullName`, `idNumber`                                                                           |\n\n### Sandbox Test Values\n\n| ID Type         | Parameter     | Value                            |\n|-----------------|---------------|----------------------------------|\n| `tin_ph`        | `idType`      | `tin_ph`                         |\n| `tin_ph`        | `fullName`    | `George Cimafranca Palomero Jr.` |\n| `tin_ph`        | `firstName`   | `George`                         |\n| `tin_ph`        | `middleName`  | `Cimafranca`                     |\n| `tin_ph`        | `lastName`    | `Palomero`                       |\n| `tin_ph`        | `suffix`      | `Jr.`                            |\n| `tin_ph`        | `idNumber`    | `123456789`                      |\n| `tin_ph`        | `gender`      | `Male`                           |\n| `tin_ph`        | `dateOfBirth` | `1970-08-24`                     |\n| `pagibig_ph`    | `idType`      | `pagibig_ph`                     |\n| `pagibig_ph`    | `fullName`    | `George Cimafranca Palomero Jr.` |\n| `pagibig_ph`    | `idNumber`    | `123456789012`                   |\n| `prclicense_ph` | `idType`      | `prclicense_ph`                  |\n| `prclicense_ph` | `fullName`    | `George Cimafranca Palomero Jr.` |\n| `prclicense_ph` | `idSubType`   | `CRIMINOLOGIST`                  |\n| `prclicense_ph` | `idNumber`    | `0123456`                        |\n| `prclicense_ph` | `dateOfBirth` | `1970-08-24`                     |\n| `nbi_ph`        | `idType`      | `nbi_ph`                         |\n| `nbi_ph`        | `fullName`    | `George Cimafranca Palomero Jr.` |\n| `nbi_ph`        | `idNumber`    | `ABC123DEF4-56GHI789J`           |\n\nUse one Sandbox record per Verification request. For inputs outside these test\nvalues, the Sandbox may not return a matched verification result.\n",
        "tags": [
          "Verification"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VerificationCreateRequest"
              },
              "examples": {
                "Example": {
                  "value": {
                    "firstName": "George",
                    "middleName": "Cimafranca",
                    "lastName": "Palomero",
                    "suffix": "Jr.",
                    "fullName": "George Cimafranca Palomero Jr.",
                    "additionalData": {
                      "dob": "1970-08-24",
                      "gender": "Male",
                      "ids": [
                        {
                          "idType": "tin_ph",
                          "idSubType": null,
                          "idNumber": "123456789"
                        }
                      ]
                    },
                    "consent": {
                      "type": "Terms And Conditions",
                      "version": 1,
                      "consentedWith": "I agree to the terms and conditions.",
                      "consentedAt": "2021-04-14T09:30:24Z",
                      "consentTemplateId": null
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerificationCreateResponse"
                },
                "examples": {
                  "Example": {
                    "value": {
                      "code": "OK",
                      "message": "Success",
                      "requestId": "5b79399a-6852-4234-bb0e-ad472648282d",
                      "data": {
                        "id": "5b79399a-6852-4234-bb0e-ad472648282d",
                        "createdAt": "2021-04-14T09:30:24Z",
                        "updatedAt": "2021-04-14T09:30:24Z",
                        "status": "PROCESSING",
                        "errorMessage": null,
                        "requestMeta": {
                          "firstName": "George",
                          "middleName": "Cimafranca",
                          "lastName": "Palomero",
                          "suffix": "Jr.",
                          "fullName": "George Cimafranca Palomero Jr.",
                          "additionalData": {
                            "dob": "1970-08-24",
                            "gender": "Male",
                            "ids": [
                              {
                                "idType": "tin_ph",
                                "idSubType": null,
                                "idNumber": "123456789"
                              }
                            ]
                          },
                          "consent": {
                            "type": "Terms And Conditions",
                            "version": 1,
                            "consentedWith": "I agree to the terms and conditions.",
                            "consentedAt": "2021-04-14T09:30:24Z",
                            "consentTemplateId": null
                          }
                        },
                        "result": null
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "operationId": "create-verification"
      }
    }
  },
  "components": {
    "schemas": {
      "ObjectMetadataRefCode": {
        "type": "string",
        "title": "ObjectMetadataRefCode",
        "description": "Request status code",
        "enum": [
          "OK",
          "CREATED",
          "INVALID_CREDENTIALS",
          "INVALID_PARAMETERS",
          "INVALID_TOKEN",
          "UNAUTHORIZED_ACCESS",
          "MISSING_RESOURCE",
          "REQUEST_LIMIT_EXCEEDED",
          "SERVER_ERROR",
          "UNSUPPORTED_METHOD",
          "SERVER_UNAVAILABLE",
          "TIME_LIMIT_EXCEEDED"
        ],
        "example": "OK",
        "x-internal": false
      },
      "ObjectMetadataRefMessage": {
        "type": "string",
        "title": "ObjectMetadataRefMessage",
        "description": "Message response to the request",
        "example": "Success",
        "x-internal": false
      },
      "ObjectMetadataRefRequestID": {
        "type": "string",
        "title": "ObjectMetadataRefRequestID",
        "description": "Unique ID that is added to the body of every response for easy traceability of the request in our logs.",
        "x-internal": false,
        "example": "5b79399a-6852-4234-bb0e-ad472648282d"
      },
      "RefDateTime": {
        "type": "string",
        "title": "Date and Time string",
        "format": "date-time",
        "example": "2021-04-14T09:30:24Z",
        "description": "Date and time"
      },
      "RefGender": {
        "type": "string",
        "title": "GenderEnum",
        "enum": [
          "Male",
          "Female",
          "Non-binary",
          null
        ],
        "example": "Male",
        "description": "Gender"
      },
      "RefDate": {
        "type": "string",
        "format": "date",
        "description": "The date, yyyy-MM-dd",
        "example": "2000-01-21"
      },
      "Consent": {
        "type": "object",
        "required": [
          "consentedAt",
          "consentedWith"
        ],
        "properties": {
          "type": {
            "type": "string",
            "description": "The internal name of your consent document (e.g. \"Terms and Conditions\" or \"Privacy Policy\"); your own reference label",
            "example": "Terms and Conditions"
          },
          "version": {
            "type": "string",
            "description": "Your internal version identifier for this consent document (e.g. \"1.0.0\")",
            "example": "1.0.0"
          },
          "consentedAt": {
            "allOf": [
              {
                "$ref": "#/components/schemas/RefDateTime"
              }
            ],
            "description": "The date and time the subject accepted your consent document, typically when they tapped \"I agree\" in your app. Not the time of this API call. Use ISO 8601 format, e.g. \"2024-04-14T09:30:24Z\""
          },
          "consentedWith": {
            "type": "string",
            "description": "The exact text of the button or checkbox the user clicked to give consent, e.g. \"I agree to the Terms and Conditions\"",
            "example": "I agree to the terms and conditions"
          },
          "consentTemplateId": {
            "type": "string",
            "description": "ID of a stored Consent Template. Retrieve from the Developer Portal or GET /consentTemplates. Overrides any inline fields above when provided."
          }
        }
      },
      "VerificationIdType": {
        "type": "string",
        "enum": [
          "tin_ph",
          "pagibig_ph",
          "prclicense_ph",
          "nbi_ph"
        ],
        "example": "tin_ph"
      },
      "VerificationId": {
        "type": "object",
        "required": [
          "idType",
          "idNumber"
        ],
        "properties": {
          "idType": {
            "allOf": [
              {
                "$ref": "#/components/schemas/VerificationIdType"
              }
            ],
            "example": "tin_ph"
          },
          "idSubType": {
            "type": "string",
            "description": "If idType = prclicense_ph, subtype should be one of the PrcProfessionEnum value.",
            "example": "CRIMINOLOGIST"
          },
          "idNumber": {
            "type": "string",
            "description": "The ID number",
            "example": "123456789"
          }
        }
      },
      "VerificationCreateRequest": {
        "type": "object",
        "required": [
          "consent"
        ],
        "properties": {
          "firstName": {
            "type": "string",
            "example": "George",
            "description": "First Name"
          },
          "middleName": {
            "type": "string",
            "example": "Cimafranca",
            "description": "Middle Name"
          },
          "lastName": {
            "type": "string",
            "example": "Palomero",
            "description": "Last Name"
          },
          "suffix": {
            "type": "string",
            "example": "Jr.",
            "description": "Suffix"
          },
          "fullName": {
            "type": "string",
            "example": "George Cimafranca Palomero Jr.",
            "description": "Full Name"
          },
          "additionalData": {
            "type": "object",
            "properties": {
              "email": {
                "type": "string",
                "description": "Email Address",
                "example": "john.doe@smile.com"
              },
              "phone": {
                "type": "string",
                "example": 6391234567890
              },
              "dob": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/RefDate"
                  }
                ],
                "example": "1970-08-24"
              },
              "gender": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/RefGender"
                  }
                ],
                "example": "Male"
              },
              "address": {
                "type": "string",
                "example": "123 Main St, Anytown, CA 12345",
                "description": "The address you want to verify"
              },
              "employer": {
                "type": "string",
                "example": "Google",
                "description": "Employer name"
              },
              "employmentStatus": {
                "type": "string",
                "description": "Employment status",
                "enum": [
                  "EMPLOYED",
                  "UNEMPLOYED",
                  "SELF-EMPLOYED",
                  "GIG",
                  "RETIRED"
                ]
              },
              "ids": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/VerificationId"
                }
              }
            }
          },
          "consent": {
            "$ref": "#/components/schemas/Consent"
          }
        }
      },
      "VerificationIdMatchResult": {
        "type": "object",
        "required": [
          "idNumber",
          "idType",
          "matches"
        ],
        "properties": {
          "idNumber": {
            "type": "string"
          },
          "idType": {
            "type": "string"
          },
          "idSubtype": {
            "type": "string"
          },
          "matches": {
            "type": "boolean"
          }
        }
      },
      "VerificationContactMatchResult": {
        "type": "object",
        "properties": {
          "value": {
            "type": "string",
            "description": "The value of the contact"
          },
          "matches": {
            "type": "boolean",
            "description": "Full match result. If request without this field or Smile do not support to match this field, then the value is null."
          },
          "disposable": {
            "type": "boolean",
            "description": "Disposable email/phone. If request without this field or Smile do not support to match this field, then the value is null."
          },
          "deliverable": {
            "type": "boolean",
            "description": "Deliverable email/phone. If request without this field or Smile do not support to match this field, then the value is null."
          },
          "active": {
            "type": "boolean",
            "description": "Active email/phone. If request without this field or Smile do not support to match this field, then the value is null."
          },
          "provider": {
            "type": "string",
            "description": "The provider of the contact"
          },
          "freeProvider": {
            "type": "boolean",
            "description": "If the provider is free provider."
          }
        }
      },
      "VerificationResult": {
        "type": "object",
        "required": [
          "finalMatches",
          "names"
        ],
        "properties": {
          "finalMatches": {
            "type": "boolean",
            "description": "The final match result"
          },
          "names": {
            "type": "object",
            "properties": {
              "firstNameMatches": {
                "type": "boolean",
                "description": "First name fuzzy match result. If request without firstName or Smile do not support to match this field, then the value is null."
              },
              "lastNameMatches": {
                "type": "boolean",
                "description": "First name fuzzy match result. If request without lastName or Smile do not support to match this field, then the value is null."
              },
              "middleNameMatches": {
                "type": "boolean",
                "description": "Middle name fuzzy match result. If request without middleName or Smile do not support to match this field, then the value is null."
              },
              "fullNameMatches": {
                "type": "boolean",
                "description": "Full name fuzzy match result. If request without fullName or Smile do not support to match this field, then the value is null."
              }
            }
          },
          "additionalData": {
            "type": "object",
            "properties": {
              "ids": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/VerificationIdMatchResult"
                }
              },
              "dobMatches": {
                "type": "boolean",
                "description": "Dob full match result. If request without dob or Smile do not support to match this field, then the value is null."
              },
              "genderMatches": {
                "type": "boolean",
                "description": "Gender full match result. If request without gender or Smile do not support to match this field, then the value is null."
              },
              "phoneMatches": {
                "$ref": "#/components/schemas/VerificationContactMatchResult"
              },
              "emailMatches": {
                "$ref": "#/components/schemas/VerificationContactMatchResult"
              },
              "addressMatches": {
                "type": "boolean",
                "description": "Address fuzzy match result. If request without address or Smile do not support to match this field, then the value is null."
              }
            }
          }
        }
      },
      "Verification": {
        "type": "object",
        "required": [
          "id",
          "createdAt",
          "status",
          "updatedAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The ID of the verification"
          },
          "createdAt": {
            "$ref": "#/components/schemas/RefDateTime"
          },
          "status": {
            "type": "string",
            "description": "The status of the verification",
            "enum": [
              "PROCESSING",
              "COMPLETED",
              "ERROR"
            ]
          },
          "updatedAt": {
            "$ref": "#/components/schemas/RefDateTime"
          },
          "errorMessage": {
            "type": "string",
            "description": "Error message when the status is error"
          },
          "requestMeta": {
            "$ref": "#/components/schemas/VerificationCreateRequest"
          },
          "result": {
            "$ref": "#/components/schemas/VerificationResult"
          }
        }
      },
      "VerificationCreateResponse": {
        "type": "object",
        "properties": {
          "code": {
            "$ref": "#/components/schemas/ObjectMetadataRefCode"
          },
          "message": {
            "$ref": "#/components/schemas/ObjectMetadataRefMessage"
          },
          "requestId": {
            "$ref": "#/components/schemas/ObjectMetadataRefRequestID"
          },
          "data": {
            "$ref": "#/components/schemas/Verification"
          }
        }
      }
    },
    "securitySchemes": {
      "basicAuth": {
        "type": "http",
        "scheme": "basic"
      }
    }
  },
  "security": [
    {
      "basicAuth": []
    }
  ]
}
```