> ## Documentation Index > Fetch the complete documentation index at: https://docs.taxrock.com/llms.txt > Use this file to discover all available pages before exploring further. # Verify a TIN > Verifies a TIN + name pair against IRS records. Requires the `verify:tins` scope. Send a TIN along with either a `businessName` or a `firstName` and `lastName`. The result indicates whether the SSN/EIN matches the entity name according to the IRS, and if not, whether the TIN has been issued. See [TIN verification results](/api-reference/tin-match-results) for every response. ## OpenAPI ````yaml api-reference/openapi.json POST /tin-match/verify openapi: 3.1.0 info: title: TaxRock Delegate API version: 1.0.0 description: >- Read a TaxRock user's tax-compliance data on that user's behalf, after the user grants consent once. A standard OAuth 2.0 Authorization Code + PKCE integration. See Getting started for the auth flow. The field-level semantics (statuses, badges, TIN censoring, balances, liens, and installment agreements) are described on the Lookup results page. servers: - url: https://delegate-demo.api.taxrock.com description: Sandbox - url: https://delegate.api.taxrock.com description: Production security: - bearerAuth: [] paths: /tin-match/verify: post: tags: - TIN Verification summary: Verify a TIN description: >- Verifies a TIN + name pair against IRS records. Requires the `verify:tins` scope. operationId: verifyTin requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/VerifyTinRequest' examples: business: summary: Verify a business value: tin: 11-1111111 businessName: Acme Trucking LLC individual: summary: Verify an individual value: tin: 111-11-1111 firstName: Jane lastName: Doe responses: '200': description: >- Verification completed. `result` carries the definitive answer; `verifiedAtUtc` is when it was produced. content: application/json: schema: $ref: '#/components/schemas/VerifyTinResponse' examples: matched: summary: Matched (name and TIN match) value: result: Matched verifiedAtUtc: '2026-07-09T18:24:05Z' mismatch: summary: Mismatched (name and TIN do not match) value: result: Mismatched verifiedAtUtc: '2026-07-09T18:24:05Z' notIssued: summary: TIN not currently issued value: result: NotIssued verifiedAtUtc: '2026-07-09T18:24:05Z' '400': description: >- The request was invalid: it failed validation, or the IRS rejected the TIN or name as malformed. Nothing counts toward usage. content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: invalidTin: summary: Malformed TIN value: error: invalid_request message: >- tin must contain nine digits; dashes and spaces are ignored. missingName: summary: No complete name shape value: error: invalid_request message: Provide businessName, or firstName and lastName. bothNameShapes: summary: Both name shapes supplied value: error: invalid_request message: Provide businessName or firstName and lastName, not both. malformedBody: summary: Unparseable request body value: error: invalid_request message: Request body is invalid or malformed JSON. irsRejected: summary: IRS rejected the TIN or name value: error: invalid_request message: The IRS rejected the TIN or name as malformed or invalid. '401': description: >- Missing or invalid access token. Refresh the token, or send the user back through the authorization flow. '403': description: >- The access token is not permitted to make this call. Two cases, told apart by the `error` field: `insufficient_scope` means the token is missing the required scope (re-run authorize requesting `verify:tins`), and `forbidden` means the connected user is not eligible or lacks permission (refreshing or reconnecting will not fix it). content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: insufficientScope: summary: Token missing the required scope value: error: insufficient_scope message: >- Access token is missing the required scope. Re-run authorize requesting: verify:tins. forbidden: summary: User not eligible or not permitted value: error: forbidden message: Caller lacks the required permission. '503': description: >- Verification deferred: a rate limit is being approached and the request was not made. Retry after the `Retry-After` interval. Deferrals do not count toward usage. See the TIN verification results page for details. headers: Retry-After: description: >- Seconds after which a retry will be past the deferral. A worst-case estimate, not a countdown; a retry may succeed much sooner. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: deferred: summary: Verification deferred (retry later) value: error: verification_deferred message: >- The IRS TIN Matching service could not verify this TIN right now. Retry after the Retry-After interval. components: schemas: VerifyTinRequest: type: object required: - tin description: >- A TIN plus exactly one name shape: `businessName`, or `firstName` and `lastName`, never both. SSNs and EINs both verify. properties: tin: type: string description: >- **Both shapes:** the TIN to verify: nine digits, with dashes and spaces ignored. examples: - 11-1111111 businessName: type: string description: '**Business shape:** the business name to verify against.' firstName: type: string description: '**Individual shape:** the individual''s first name.' lastName: type: string description: '**Individual shape:** the individual''s last name.' VerifyTinResponse: type: object required: - result - verifiedAtUtc properties: result: $ref: '#/components/schemas/TinVerificationResult' verifiedAtUtc: type: string format: date-time description: When the answer was produced. ApiError: type: object required: - error - message properties: error: type: string description: >- Machine-readable error code, e.g. `invalid_ein` or `invalid_request`. message: type: string description: Human-readable explanation. TinVerificationResult: type: string enum: - Matched - Mismatched - NotIssued description: >- The definitive verification result. See the TIN verification results page for the full meaning of each value. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- The access token obtained from the OAuth flow, sent as a Bearer credential. ````