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

# Verify tax ID

> Verify a Spanish tax ID (NIF/CIF) against the AEAT census. The endpoint
always reports whether AEAT identified the tax ID. When `correct` is
`true` and the tax ID is identified, the official name registered with
AEAT is also returned.

Verify a Spanish tax ID (NIF/CIF) against the AEAT census without going through the registration flow. The response always reports whether AEAT identified the tax ID; set `correct` to `true` to also receive the official name registered with AEAT when the tax ID is identified.


## OpenAPI

````yaml POST /apps/gov-es/v1/lookup
openapi: 3.1.0
info:
  contact:
    email: dev@invopop.com
    name: Invopop Developers
  description: Set of end-points that help you test access to the Spain app API.
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  title: Spain Service API
  version: 0.1.0
servers:
  - description: production
    url: https://api.invopop.com
security:
  - InvopopAuth: []
paths:
  /apps/gov-es/v1/lookup:
    post:
      description: |-
        Verify a Spanish tax ID (NIF/CIF) against the AEAT census. The endpoint
        always reports whether AEAT identified the tax ID. When `correct` is
        `true` and the tax ID is identified, the official name registered with
        AEAT is also returned.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                tax_id:
                  description: Spanish tax ID (NIF/CIF) to verify against AEAT.
                  type: string
                  example: B98602031
                name:
                  description: |-
                    Name to check against the tax ID. For individuals AEAT
                    verifies that the name matches the tax ID on record; for
                    companies the name is not required to confirm the tax ID
                    exists.
                  type: string
                  example: Provide One SL
                correct:
                  description: |-
                    When `true` and the tax ID is identified, the response also
                    includes the official `name` as registered with AEAT.
                  type: boolean
                  default: false
              required:
                - tax_id
      responses:
        '200':
          description: The verification completed and the result is reported in the body.
          content:
            application/json:
              schema:
                type: object
                properties:
                  identified:
                    description: Whether AEAT identified the tax ID.
                    type: boolean
                  name:
                    description: |-
                      Official name registered with AEAT. Only present when
                      `correct` was `true` in the request and the tax ID was
                      identified.
                    type: string
        '400':
          description: >-
            Bad Request - The request body could not be parsed or `tax_id` was
            empty.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    description: Details of the error.
        '422':
          description: >-
            Unprocessable Entity - The tax ID could not be verified (invalid or
            unverifiable input).
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    description: Details of the error.
        '500':
          description: Internal Server Error - The upstream AEAT lookup failed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    description: Details of the error.
components:
  securitySchemes:
    InvopopAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        Use the `Bearer` scheme with a valid JWT token to authenticate requests.

        Example: `Authorization: Bearer <token>`

````