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

# Validate national ID number

> ### Validates a national ID number (e.g., Social Security Number) with the provided data

#### When to use this endpoint

- Use this endpoint to validate national ID numbers (such as Social Security Numbers) against official government databases 
without requiring document uploads or end-user interaction

- Common use cases include:
  - Validating US Social Security Numbers (SSN) against national databases
  - Verifying person data matches government records
  - Performing registry-based identity checks for regulatory compliance
  - Quick identity validation without document capture

#### How this endpoint works

- When you call this endpoint:
  - A verification session is automatically created and submitted
  - The API response returns only the request status and basic session data
  - Validation results (person data) are sent via [decision webhook](https://devdocs.veriff.com/docs/decision-webhook)
  - Media upload is NOT used for registry verification

#### Default vs sync-api versions

- This is the **default /validate-registry** endpoint. It uses the standard API URL 
`https://example-base-url/v1/validate-registry` and delivers person data via webhook.
- There is also a **sync-api /validate-registry** version that returns person data directly in the API response payload. 
- The sync-api version is not available by default - contact Veriff to enable it
see its [API documentation](https://devdocs.veriff.com/apidocs/validate-registry-3) for more info.

#### Required data combinations

- To perform SSN validation, you must provide:
  - `idNumber` (SSN) - REQUIRED
  - `fullName` OR (`firstName` + `lastName`) - REQUIRED (one combination)
  - `dateOfBirth` OR `address` data - REQUIRED (one combination)

- If providing `address` data, send EITHER:
  - `fullAddress` (full address as single string), OR
  - `street` + `houseNumber` + `postcode` (structured address components)

- Click on the "Show example" button in the "Body parameters" section to see some example request payloads.

#### Implementation notes

- Validation results are sent via decision webhook
- Optional fields `phoneNumber`, `vendorData`, and `endUserId` are strongly recommended for improved fraud prevention
- Always ensure that you use the correct API URL to send requests. See the 
  [API URL section](https://devdocs.veriff.com/apidocs/veriff-public-api-guides#api-url) for more info
- The order of parameters in the real API response can differ from the order you see in this documentation. 
  This is expected and part of the 
  [Backwards compatible changes](https://devdocs.veriff.com/apidocs/veriff-public-api-guides#backwards-compatible-changes) requirements


## OpenAPI

````json POST /v1/validate-registry
{
  "openapi": "3.0.0",
  "info": {
    "title": "Veriff Public API",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://example-base-url"
    }
  ],
  "tags": [
    {
      "name": "Session management",
      "description": "Create and manage verification sessions"
    },
    {
      "name": "Data submission",
      "description": "Upload media and submit verification data during the session"
    },
    {
      "name": "Session results",
      "description": "Retrieve verification decisions and results"
    },
    {
      "name": "Media management",
      "description": "Access and download verification media files and media file-related data"
    },
    {
      "name": "Database verification",
      "description": "Validate identity against national registries and databases"
    }
  ],
  "paths": {
    "/v1/validate-registry": {
      "post": {
        "summary": "Validate national ID number",
        "tags": [
          "Database verification"
        ],
        "description": "### Validates a national ID number (e.g., Social Security Number) with the provided data\n\n#### When to use this endpoint\n\n- Use this endpoint to validate national ID numbers (such as Social Security Numbers) against official government databases \nwithout requiring document uploads or end-user interaction\n\n- Common use cases include:\n  - Validating US Social Security Numbers (SSN) against national databases\n  - Verifying person data matches government records\n  - Performing registry-based identity checks for regulatory compliance\n  - Quick identity validation without document capture\n\n#### How this endpoint works\n\n- When you call this endpoint:\n  - A verification session is automatically created and submitted\n  - The API response returns only the request status and basic session data\n  - Validation results (person data) are sent via [decision webhook](https://devdocs.veriff.com/docs/decision-webhook)\n  - Media upload is NOT used for registry verification\n\n#### Default vs sync-api versions\n\n- This is the **default /validate-registry** endpoint. It uses the standard API URL \n`https://example-base-url/v1/validate-registry` and delivers person data via webhook.\n- There is also a **sync-api /validate-registry** version that returns person data directly in the API response payload. \n- The sync-api version is not available by default - contact Veriff to enable it\nsee its [API documentation](https://devdocs.veriff.com/apidocs/validate-registry-3) for more info.\n\n#### Required data combinations\n\n- To perform SSN validation, you must provide:\n  - `idNumber` (SSN) - REQUIRED\n  - `fullName` OR (`firstName` + `lastName`) - REQUIRED (one combination)\n  - `dateOfBirth` OR `address` data - REQUIRED (one combination)\n\n- If providing `address` data, send EITHER:\n  - `fullAddress` (full address as single string), OR\n  - `street` + `houseNumber` + `postcode` (structured address components)\n\n- Click on the \"Show example\" button in the \"Body parameters\" section to see some example request payloads.\n\n#### Implementation notes\n\n- Validation results are sent via decision webhook\n- Optional fields `phoneNumber`, `vendorData`, and `endUserId` are strongly recommended for improved fraud prevention\n- Always ensure that you use the correct API URL to send requests. See the \n  [API URL section](https://devdocs.veriff.com/apidocs/veriff-public-api-guides#api-url) for more info\n- The order of parameters in the real API response can differ from the order you see in this documentation. \n  This is expected and part of the \n  [Backwards compatible changes](https://devdocs.veriff.com/apidocs/veriff-public-api-guides#backwards-compatible-changes) requirements\n",
        "parameters": [
          {
            "name": "X-AUTH-CLIENT",
            "in": "header",
            "required": "true",
            "schema": {
              "type": "string"
            },
            "description": "Your integration's API key (occasionally referred to as the \"Token\", \"API public key\" or \"Publishable key\"). \nRequired for all API requests.\n\nYou can find your API key in the Veriff Customer Portal > Settings > API keys.\n",
            "example": "your-api-public-key"
          },
          {
            "name": "Content-Type",
            "in": "header",
            "required": "true",
            "schema": {
              "type": "string",
              "enum": [
                "application/json"
              ]
            },
            "description": "Must be application/json",
            "example": "application/json"
          }
        ],
        "requestBody": {
          "required": "true",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ValidateRegistryRequest"
              },
              "examples": {
                "fullName_with_dateOfBirth": {
                  "description": "Validates using `idNumber` + `fullName` + `dateOfBirth`.\n\nNote: `phoneNumber`, `vendorData`, and `endUserId` are optional but strongly recommended for \nimproved fraud prevention.\n",
                  "value": {
                    "verification": {
                      "callback": "https://exampleURL.com/callback",
                      "person": {
                        "idNumber": "123456789",
                        "fullName": "John Smith",
                        "dateOfBirth": "1980-03-06",
                        "phoneNumber": "+00 123 456 789"
                      },
                      "vendorData": "11111111",
                      "endUserId": "fa820aba-019f-455a-ae81-cfca8075bc3f"
                    }
                  }
                },
                "fullName_with_fullAddress": {
                  "description": "Validates using `idNumber` + `fullName` + `fullAddress`.\n\nNote: `phoneNumber`, `vendorData`, and `endUserId` are optional but strongly recommended for \nimproved fraud prevention.\n",
                  "value": {
                    "verification": {
                      "callback": "https://exampleURL.com/callback",
                      "person": {
                        "idNumber": "123456789",
                        "fullName": "John Smith",
                        "phoneNumber": "+00 123 456 789"
                      },
                      "address": {
                        "fullAddress": "3, 123, Main Street, My County, Anytown, 12345"
                      },
                      "vendorData": "11111111",
                      "endUserId": "fa820aba-019f-455a-ae81-cfca8075bc3f"
                    }
                  }
                },
                "fullName_with_structured_address": {
                  "description": "Validates using `idNumber` + `fullName` + structured `address` (`street` + `houseNumber` + `postcode`).\n\nNote: `phoneNumber`, `vendorData`, and `endUserId` are optional but strongly recommended for \nimproved fraud prevention.\n",
                  "value": {
                    "verification": {
                      "callback": "https://exampleURL.com/callback",
                      "person": {
                        "idNumber": "123456789",
                        "fullName": "John Smith",
                        "phoneNumber": "+00 123 456 789"
                      },
                      "address": {
                        "street": "Main Street",
                        "houseNumber": "123",
                        "postcode": "12345"
                      },
                      "vendorData": "11111111",
                      "endUserId": "fa820aba-019f-455a-ae81-cfca8075bc3f"
                    }
                  }
                },
                "firstName_lastName_with_dateOfBirth": {
                  "description": "Validates using `idNumber` + `firstName` + `lastName` + `dateOfBirth`.\n\nNote: `phoneNumber`, `vendorData`, and `endUserId` are optional but strongly recommended for \nimproved fraud prevention.\n",
                  "value": {
                    "verification": {
                      "callback": "https://exampleURL.com/callback",
                      "person": {
                        "idNumber": "123456789",
                        "firstName": "John",
                        "lastName": "Smith",
                        "dateOfBirth": "1980-03-06",
                        "phoneNumber": "+00 123 456 789"
                      },
                      "vendorData": "11111111",
                      "endUserId": "fa820aba-019f-455a-ae81-cfca8075bc3f"
                    }
                  }
                },
                "firstName_lastName_with_fullAddress": {
                  "description": "Validates using `idNumber` + `firstName` + `lastName` + `fullAddress`.\n\nNote: `phoneNumber`, `vendorData`, and `endUserId` are optional but strongly recommended for \nimproved fraud prevention.\n",
                  "value": {
                    "verification": {
                      "callback": "https://exampleURL.com/callback",
                      "person": {
                        "idNumber": "123456789",
                        "firstName": "John",
                        "lastName": "Smith",
                        "phoneNumber": "+00 123 456 789"
                      },
                      "address": {
                        "fullAddress": "3, 123, Main Street, My County, Anytown, 12345"
                      },
                      "vendorData": "11111111",
                      "endUserId": "fa820aba-019f-455a-ae81-cfca8075bc3f"
                    }
                  }
                },
                "firstName_lastName_with_structured_address": {
                  "description": "Validates using `idNumber` + `firstName` + `lastName` + structured `address` \n(`street` + `houseNumber` + `postcode`).\n\nNote: `phoneNumber`, `vendorData`, and `endUserId` are optional but strongly recommended for \nimproved fraud prevention.\n",
                  "value": {
                    "verification": {
                      "callback": "https://exampleURL.com/callback",
                      "person": {
                        "idNumber": "123456789",
                        "firstName": "John",
                        "lastName": "Smith",
                        "phoneNumber": "+00 123 456 789"
                      },
                      "address": {
                        "street": "Main Street",
                        "houseNumber": "123",
                        "postcode": "12345"
                      },
                      "vendorData": "11111111",
                      "endUserId": "fa820aba-019f-455a-ae81-cfca8075bc3f"
                    }
                  }
                },
                "minimal_required_only": {
                  "description": "Minimal payload with only required fields.\n\nWarning: Without optional fraud prevention fields (`phoneNumber`, `vendorData`, `endUserId`), \nfraud detection may be limited.\n",
                  "value": {
                    "verification": {
                      "person": {
                        "idNumber": "123456789",
                        "fullName": "John Smith",
                        "dateOfBirth": "1980-03-06"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session created successfully",
            "headers": {
              "X-AUTH-CLIENT": {
                "description": "API key echoed back in response.",
                "schema": {
                  "type": "string"
                }
              },
              "X-HMAC-SIGNATURE": {
                "description": "Response body signed with the shared secret key. Required to authenticate the response sender.",
                "schema": {
                  "type": "string"
                }
              },
              "Content-Type": {
                "description": "Response content type.",
                "schema": {
                  "type": "string",
                  "example": "application/json"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidateRegistryResponse"
                },
                "examples": {
                  "session_created": {
                    "description": "Registry validation session created successfully. The session will be automatically \nsubmitted for validation, and results will be sent via decision webhook.\n",
                    "value": {
                      "status": "success",
                      "verification": {
                        "id": "f8b2c4d6-1a3e-4f9b-8c2d-5e7a9b1c3d4f",
                        "vendorData": "1234567890",
                        "status": "created",
                        "sessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uX2lkIjoiZjhiMmM0ZDYtMWEzZS00ZjliLThjMmQtNWU3YTliMWMzZDRmIn0..."
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing or invalid required fields",
            "headers": {
              "X-AUTH-CLIENT": {
                "description": "API key echoed back in response.",
                "schema": {
                  "type": "string"
                },
                "example": "your-api-public-key"
              },
              "X-HMAC-SIGNATURE": {
                "description": "Response body signed with the shared secret key. Required to authenticate the response sender.",
                "schema": {
                  "type": "string"
                },
                "example": "z6y5x4w3v2u1t0s9r8q7p6o5n4m3l2k1j0i9h8g7f6e5d4c3b2a1"
              },
              "Content-Type": {
                "description": "Response content type.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "application/json"
                  ]
                },
                "example": "application/json"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestErrorResponse"
                },
                "examples": {
                  "missing_name_data": {
                    "description": "Missing name data - Required field `fullName` or (`firstName` + `lastName`) not provided",
                    "value": {
                      "status": "failed",
                      "code": "1102",
                      "message": "Request person is missing required field fullName or (firstName + lastName)"
                    }
                  },
                  "missing_dateOfBirth_or_address": {
                    "description": "Missing date of birth OR address - Required field `dateOfBirth` or `address` not provided",
                    "value": {
                      "status": "failed",
                      "code": "1102",
                      "message": "Request is missing required field 'dateOfBirth' or 'address'"
                    }
                  },
                  "missing_address_components": {
                    "description": "Missing address components - Required field `fullAddress` or \n(`street` + `houseNumber` + `postcode`) not provided\n",
                    "value": {
                      "status": "failed",
                      "code": "1102",
                      "message": "Request address is missing required field fullAddress or (street + houseNumber + postcode)"
                    }
                  },
                  "missing_idNumber": {
                    "description": "Missing ID number - Required field `idNumber` not provided",
                    "value": {
                      "status": "failed",
                      "code": "1102",
                      "message": "Request is missing required field idNumber"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - HMAC signature validation failed",
            "headers": {
              "X-AUTH-CLIENT": {
                "description": "API key echoed back in response.",
                "schema": {
                  "type": "string"
                },
                "example": "your-api-public-key"
              },
              "X-HMAC-SIGNATURE": {
                "description": "Response body signed with the shared secret key. Required to authenticate the response sender.",
                "schema": {
                  "type": "string"
                },
                "example": "z6y5x4w3v2u1t0s9r8q7p6o5n4m3l2k1j0i9h8g7f6e5d4c3b2a1"
              },
              "Content-Type": {
                "description": "Response content type.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "application/json"
                  ]
                },
                "example": "application/json"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedErrorResponse"
                },
                "example": {
                  "status": "failed",
                  "code": "1812",
                  "message": "Signature a1b2c3d4e5f6 is not a valid SHA256 hash"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ValidateRegistryRequest": {
        "type": "object",
        "required": [
          "verification"
        ],
        "properties": {
          "verification": {
            "type": "object",
            "description": "Verification object",
            "required": [
              "person"
            ],
            "properties": {
              "callback": {
                "type": "string",
                "description": "The callback URL to where the end-user is redirected after the verification session is completed. \n\nDefault is visible in the Veriff Customer Portal > Settings. Changing the value in this request body \nwill overwrite the default callback URL, but it will not change the callback URL that is visible \nin the Customer Portal.\n",
                "example": "https://exampleURL.com/callback"
              },
              "person": {
                "type": "object",
                "description": "Data about the person being verified.",
                "required": [
                  "idNumber"
                ],
                "properties": {
                  "idNumber": {
                    "type": "string",
                    "description": "Person's national ID number (SSN).",
                    "example": "123456789"
                  },
                  "firstName": {
                    "type": "string",
                    "description": "Person's first name. Required if `fullName` is not provided.",
                    "example": "John"
                  },
                  "lastName": {
                    "type": "string",
                    "description": "Person's last name. Required if `fullName` is not provided.",
                    "example": "Smith"
                  },
                  "fullName": {
                    "type": "string",
                    "description": "Person's full name. Required if `firstName` + `lastName` is not provided.",
                    "example": "John Smith"
                  },
                  "phoneNumber": {
                    "type": "string",
                    "description": "Person's phone number, can include numbers, whitespaces and the \"+\" sign in front.",
                    "example": "+00 123 456 789"
                  },
                  "dateOfBirth": {
                    "type": "string",
                    "format": "date",
                    "description": "Person's date of birth in YYYY-MM-DD format. Required if `address` is not provided.",
                    "example": "1980-03-06"
                  }
                }
              },
              "address": {
                "type": "object",
                "description": "Data about the address of the person being verified.",
                "properties": {
                  "fullAddress": {
                    "type": "string",
                    "description": "Full address. Required if `street` + `houseNumber` + `postcode` are not provided.",
                    "example": "3, 123, Main Street, My County, Anytown, 12345"
                  },
                  "street": {
                    "type": "string",
                    "description": "Street name. Required if `fullAddress` is not provided.",
                    "example": "Main Street"
                  },
                  "houseNumber": {
                    "type": "string",
                    "description": "House number. Required if `fullAddress` is not provided.",
                    "example": "123"
                  },
                  "postcode": {
                    "type": "string",
                    "description": "Postal code. Required if `fullAddress` is not provided.",
                    "example": "12345"
                  },
                  "city": {
                    "type": "string",
                    "description": "Any human settlement, including cities, towns, villages, hamlets, localities, etc.",
                    "example": "AnyCity"
                  },
                  "state": {
                    "type": "string",
                    "description": "A first-level administrative division. For example, Scotland, Northern Ireland, Wales, and England \nin the UK are mapped to \"state\" as well (convention used in OSM, GeoPlanet, etc.)\n",
                    "example": "AnyState"
                  },
                  "unit": {
                    "type": "string",
                    "description": "An apartment, unit, office, lot, or other secondary unit designator.",
                    "example": "3"
                  }
                }
              },
              "vendorData": {
                "type": "string",
                "description": "The unique identifier that you created for your end-user. It can be max 1,000 characters long and \ncontain only non-semantic data that can not be resolved or used outside your systems or environments. \nVeriff returns it unmodified in webhooks and API response payloads, or as `null` if not provided.\n",
                "example": "11111111"
              },
              "endUserId": {
                "type": "string",
                "format": "uuid",
                "description": "End-user-specific UUID created by the customer to identify the end-user. Returned unmodified in \nwebhooks and public API calls, or as `null` if not provided.\n",
                "example": "fa820aba-019f-455a-ae81-cfca8075bc3f"
              }
            }
          }
        }
      },
      "ValidateRegistryResponse": {
        "type": "object",
        "required": [
          "status",
          "verification"
        ],
        "properties": {
          "status": {
            "type": "string",
            "description": "API request status.",
            "example": "success"
          },
          "verification": {
            "type": "object",
            "description": "Verification object.",
            "required": [
              "id",
              "vendorData",
              "status",
              "sessionToken"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "UUID v4 which identifies the verification session.",
                "example": "123e4567-e89b-12d3-a456-426614174000"
              },
              "vendorData": {
                "type": "string",
                "nullable": "true",
                "description": "The unique identifier that you created for your end-user. It can be max 1,000 \ncharacters long and contain only non-semantic data that can not be resolved or used \noutside your systems or environments. Veriff returns it unmodified in webhooks and \nAPI response payloads, or as `null` if not provided.\n",
                "example": "1234567890"
              },
              "status": {
                "type": "string",
                "description": "Verification session status.",
                "example": "created"
              },
              "sessionToken": {
                "type": "string",
                "description": "Session-specific token of the verification.",
                "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
              }
            }
          }
        }
      },
      "BadRequestErrorResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "fail"
            ],
            "example": "fail"
          },
          "code": {
            "type": "string",
            "example": "1101"
          },
          "message": {
            "type": "string",
            "example": "Validation failed"
          }
        },
        "required": [
          "status",
          "code",
          "message"
        ]
      },
      "UnauthorizedErrorResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "fail"
            ],
            "example": "fail"
          },
          "code": {
            "type": "string",
            "example": "1101"
          },
          "message": {
            "type": "string",
            "example": "Mandatory X-AUTH-CLIENT header containing the API key is missing from the request."
          }
        },
        "required": [
          "status",
          "code",
          "message"
        ]
      }
    }
  }
}
````