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

# Verify TIN

> Verifies a Tax Identification Number (EIN or SSN) and associated name against IRS records. Unlike `POST /business/verification`, this runs only the IRS TIN Matching check and does not perform registry lookup or risk assessment. When the IRS service is unavailable, returns `matched: null` with `status: pending` and a machine-readable `unavailable_reason` so callers can retry later. In test mode the check is always simulated — the IRS is never contacted, and `metadata._simulate` selects the outcome (see the `metadata` field).



## OpenAPI

````yaml /api-reference/v1/openapi.json post /v1/tin/verification
openapi: 3.0.0
info:
  title: Palm Partner API
  description: >-
    The Palm API is identity verification and compliance infrastructure for US
    businesses: onboard businesses, verify businesses and people (KYB/KYC)
    against authoritative sources, monitor them for changes in real time, and
    act on their behalf through filings, formation, and registered agent
    services.
  version: '1.0'
  contact:
    name: Palm Support
    url: https://getpalm.com
    email: support@getpalm.com
  termsOfService: https://getpalm.com/terms
  license:
    name: Proprietary
    url: https://getpalm.com/license
servers:
  - url: https://api.getpalm.com
    description: Production
security: []
tags:
  - name: Registry
    description: Search business registries
  - name: Business
    description: Manage the businesses in your portfolio
  - name: User
    description: Manage the people in your portfolio
  - name: Verification
    description: Identity and business verification
  - name: Monitor
    description: Continuous monitoring of businesses
paths:
  /v1/tin/verification:
    post:
      tags:
        - Verification
      summary: Verify TIN
      description: >-
        Verifies a Tax Identification Number (EIN or SSN) and associated name
        against IRS records. Unlike `POST /business/verification`, this runs
        only the IRS TIN Matching check and does not perform registry lookup or
        risk assessment. When the IRS service is unavailable, returns `matched:
        null` with `status: pending` and a machine-readable `unavailable_reason`
        so callers can retry later. In test mode the check is always simulated —
        the IRS is never contacted, and `metadata._simulate` selects the outcome
        (see the `metadata` field).
      operationId: verifyTin
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TinVerificationRequest'
            examples:
              ein:
                summary: EIN (business)
                value:
                  tin: 12-3456789
                  tin_type: ein
                  name: Acme Corporation
                  reference_id: tin_req_12345
              ssn:
                summary: SSN (individual)
                value:
                  tin: 123-45-6789
                  tin_type: ssn
                  name: Jane Doe
                  reference_id: tin_req_12346
              simulated_no_match:
                summary: Test mode — simulate a failed match
                value:
                  tin: 12-3456789
                  tin_type: ein
                  name: Acme Corporation
                  metadata:
                    _simulate: no_match
      responses:
        '201':
          description: >-
            TIN verification completed (matched or not matched) or pending (IRS
            temporarily unavailable).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TinVerificationResponse'
              examples:
                matched:
                  summary: EIN and name match IRS records
                  value:
                    verification_id: 550e8400-e29b-41d4-a716-446655440000
                    object: tin_verification
                    tin_type: ein
                    matched: true
                    status: completed
                    reference_id: tin_req_12345
                    created_at: '2026-04-22T05:33:01.665Z'
                    verified_at: '2026-04-22T05:33:01.665Z'
                not_matched:
                  summary: EIN on file but name does not match
                  value:
                    verification_id: 8f14e45f-ceea-467a-9575-2b0b8f1b1f01
                    object: tin_verification
                    tin_type: ein
                    matched: false
                    status: completed
                    reference_id: tin_req_12345
                    created_at: '2026-04-22T05:33:01.665Z'
                    verified_at: '2026-04-22T05:33:01.665Z'
                pending:
                  summary: IRS TIN Matching service unavailable — retry later
                  value:
                    verification_id: 1ecaf2a6-b4f6-4810-a45e-b4abe1be19e5
                    object: tin_verification
                    tin_type: ein
                    matched: null
                    status: pending
                    unavailable_reason: tin_matching_service_unavailable
                    reference_id: tin_req_12345
                    created_at: '2026-04-22T05:33:01.665Z'
        '400':
          description: Invalid TIN format or missing required fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetail'
              examples:
                invalid_ein_format:
                  summary: EIN is not 9 digits
                  value:
                    type: https://api.getpalm.com/problems/validation_error
                    title: Validation Error
                    status: 400
                    detail: Request validation failed
                    instance: /tin/verification
                    errors:
                      - field: unknown
                        message: 'Invalid EIN format: must be 9 digits, got 5'
                missing_tin_type:
                  summary: Required `tin_type` missing
                  value:
                    type: https://api.getpalm.com/problems/validation_error
                    title: Validation Error
                    status: 400
                    detail: Request validation failed
                    instance: /tin/verification
                    errors:
                      - field: tin_type
                        message: 'tin_type must be one of the following values: ein, ssn'
        '401':
          description: Unauthorized — invalid or missing API key / bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationProblemDetail'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitProblemDetail'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalErrorProblemDetail'
      security:
        - ApiKey: []
components:
  schemas:
    TinVerificationRequest:
      type: object
      properties:
        tin:
          type: string
          description: >-
            Tax Identification Number to verify. For EIN use `XX-XXXXXXX` or 9
            digits. For SSN use `XXX-XX-XXXX` or 9 digits.
          example: 12-3456789
        name:
          type: string
          description: >-
            Name associated with the TIN. For EIN this is the legal business
            name. For SSN this is the individual's full name (`First Last` or
            `First Middle Last`).
          example: Acme Corporation
        tin_type:
          type: string
          description: >-
            Type of TIN being verified — selects the EIN (business) vs SSN
            (individual) validation path.
          enum:
            - ein
            - ssn
          example: ein
        reference_id:
          type: string
          description: >-
            Partner-provided reference ID; echoed back in the response for
            tracking.
          example: tin_req_12345
        metadata:
          type: object
          description: >-
            Custom metadata.


            In **test mode** (`sk_test_` key), TIN verification is **always
            simulated** — it never contacts the IRS, so no-directive test
            requests return a deterministic match rather than a real verdict.
            The reserved key `_simulate` selects the outcome:


            - `match` (default) → `matched: true`, `status: completed`

            - `no_match` → `matched: false`, `status: completed`

            - `unavailable` → `matched: null`, `status: pending` with
            `unavailable_reason` (the IRS-outage shape)


            Malformed TINs still return the same `tin_matching_invalid_format`
            error as live mode. Ignored in live mode.
          example:
            external_id: tin_789
            source: 1099_processing
      required:
        - tin
        - name
        - tin_type
    TinVerificationResponse:
      type: object
      properties:
        verification_id:
          type: string
          description: Unique TIN verification ID (UUID v4).
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        object:
          type: string
          description: Object type — always the literal string `tin_verification`.
          enum:
            - tin_verification
          example: tin_verification
        tin_type:
          type: string
          description: >-
            Type of TIN that was verified (echoes the `tin_type` from the
            request).
          enum:
            - ein
            - ssn
          example: ein
        matched:
          type: boolean
          description: >-
            Whether the TIN matched the provided name at the IRS. `true` =
            match, `false` = no match, `null` = match could not be determined
            (e.g., IRS service unavailable — see `unavailable_reason`).
          nullable: true
          example: true
        status:
          type: string
          description: >-
            Current status of the verification. `completed` when IRS returned a
            definitive answer; `pending` when IRS was unavailable and the caller
            should retry.
          enum:
            - pending
            - in_progress
            - completed
            - failed
          example: completed
        unavailable_reason:
          description: >-
            Machine-readable reason the verification could not be completed.
            Only present when `status === "pending"` or an error occurred.
          example: tin_matching_service_unavailable
          allOf:
            - $ref: '#/components/schemas/TinUnavailableReason'
        reference_id:
          type: string
          description: >-
            Partner-provided reference ID — echoed back only if one was supplied
            in the request.
          example: tin_req_12345
        created_at:
          type: string
          description: ISO 8601 timestamp of when the verification record was created.
          format: date-time
          example: '2026-04-17T10:30:00Z'
        verified_at:
          type: string
          description: >-
            ISO 8601 timestamp of when the TIN was verified against IRS records.
            Only present when `status === "completed"`.
          format: date-time
          example: '2026-04-17T10:30:01Z'
      required:
        - verification_id
        - object
        - tin_type
        - matched
        - status
        - created_at
    ValidationProblemDetail:
      type: object
      properties:
        type:
          type: string
          example: https://api.getpalm.com/problems/validation_error
        title:
          type: string
          example: Validation Error
        status:
          type: number
          example: 400
        detail:
          type: string
          example: Request validation failed
        instance:
          type: string
          example: /business/registry/search
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ValidationErrorField'
      required:
        - type
        - title
        - status
        - detail
        - instance
        - errors
    AuthenticationProblemDetail:
      type: object
      properties:
        type:
          type: string
          example: https://api.getpalm.com/problems/authentication_error
        title:
          type: string
          example: Unauthorized
        status:
          type: number
          example: 401
        detail:
          type: string
          example: >-
            No valid authentication provided. Please provide one of the accepted
            authentication methods.
        instance:
          type: string
          example: /business/registry/search
      required:
        - type
        - title
        - status
        - detail
        - instance
    RateLimitProblemDetail:
      type: object
      properties:
        type:
          type: string
          example: https://api.getpalm.com/problems/rate_limit_exceeded
        title:
          type: string
          example: Too Many Requests
        status:
          type: number
          example: 429
        detail:
          type: string
          example: Rate limit exceeded. Please retry after 60 seconds.
        instance:
          type: string
          example: /business/registry/search
        retry_after:
          type: number
          example: 60
        limit:
          type: number
          example: 100000
        remaining:
          type: number
          example: 0
        reset:
          type: number
          example: 1738540800
      required:
        - type
        - title
        - status
        - detail
        - instance
    InternalErrorProblemDetail:
      type: object
      properties:
        type:
          type: string
          example: https://api.getpalm.com/problems/internal_error
        title:
          type: string
          example: Internal Server Error
        status:
          type: number
          example: 500
        detail:
          type: string
          example: >-
            An internal server error occurred. Please contact support if this
            persists.
        instance:
          type: string
          example: /business/registry/search
      required:
        - type
        - title
        - status
        - detail
        - instance
    TinUnavailableReason:
      type: string
      enum:
        - tin_matching_service_unavailable
      description: >-
        Machine-readable reason the verification could not be completed. Only
        present when `status === "pending"` or an error occurred.
    ValidationErrorField:
      type: object
      properties:
        field:
          type: string
          example: name
          description: Field name that failed validation
        message:
          type: string
          example: name should not be empty
          description: Validation error message
        code:
          type: string
          example: NOT_EMPTY
          description: Error code
      required:
        - field
        - message
  securitySchemes:
    ApiKey:
      scheme: bearer
      bearerFormat: opaque
      type: http
      description: 'Enter your API key in the format: sk_test_xxxxx or sk_live_xxxxx'

````