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

# PGFN Debts Search

> Search the active debts Brazilian companies owe the Union in the dívida ativa (Procuradoria-Geral da Fazenda Nacional): federal taxes, social security contributions and the FGTS, by company name, CNPJ or its 8-character root, regime, state, status, the company's role in the debt, whether it is in court, and an amount range. Largest amount first, pages of up to 50. Companies only. Served by Croma (`as_of` says how current the data is), refreshed with each quarterly release.

**Dataset endpoint**: answers from the whole source in milliseconds and carries `as_of`.



## OpenAPI

````yaml /api-reference/openapi.json post /br/pgfn/debts-search/v1
openapi: 3.1.0
info:
  title: Croma Marketplace API
  version: 1.0.0
  description: >-
    Government-data APIs for Colombia, Peru, Mexico, and global web search.
    Croma normalizes public-sector data into structured JSON for product teams
    and AI agents.


    Every operation is a POST with a JSON body and an organization API key as a
    bearer token; every operation is an idempotent lookup and accepts an
    optional `Idempotency-Key` header. Paths carry their major version (`/v1`);
    the versioning and deprecation policy, including the `Deprecation` and
    `Sunset` headers a retiring endpoint sends, is at
    https://docs.usecroma.com/versioning. Rate limits are per organization and
    reported on every response (`RateLimit-Policy`, `X-RateLimit-*`):
    https://docs.usecroma.com/rate-limits.
  termsOfService: https://usecroma.com/en/terms
  contact:
    name: Croma support
    url: https://usecroma.com/en/support
    email: tomas@usecroma.com
servers:
  - url: https://api.croma.run
security: []
paths:
  /br/pgfn/debts-search/v1:
    post:
      tags:
        - Brazil
        - Procuradoria-Geral da Fazenda Nacional (PGFN)
      summary: PGFN Debts Search
      description: >-
        Search the active debts Brazilian companies owe the Union in the dívida
        ativa (Procuradoria-Geral da Fazenda Nacional): federal taxes, social
        security contributions and the FGTS, by company name, CNPJ or its
        8-character root, regime, state, status, the company's role in the debt,
        whether it is in court, and an amount range. Largest amount first, pages
        of up to 50. Companies only. Served by Croma (`as_of` says how current
        the data is), refreshed with each quarterly release.


        **Dataset endpoint**: answers from the whole source in milliseconds and
        carries `as_of`.
      operationId: pgfn_debts_search
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: []
              properties:
                query:
                  type: string
                  maxLength: 200
                  default: ''
                  description: Palabras a buscar en los nombres (opcional).
                document_number:
                  type: string
                  pattern: >-
                    ^(?:[A-Za-z0-9]{8}|[A-Za-z0-9]{12}\d{2}|[A-Za-z0-9]{2}\.[A-Za-z0-9]{3}\.[A-Za-z0-9]{3}(?:\/[A-Za-z0-9]{4}-\d{2})?)?$
                  default: ''
                  description: >-
                    CNPJ de la empresa deudora, con o sin puntuación, p. ej.
                    `12.345.678/0001-90`, o su raíz de 8 caracteres para todos
                    sus establecimientos (opcional).
                regime:
                  type: string
                  enum:
                    - ''
                    - nao_previdenciario
                    - previdenciario
                    - fgts
                  default: ''
                  description: >-
                    Tipo de deuda: `nao_previdenciario` (tributos y demás),
                    `previdenciario` (contribuciones a la seguridad social) o
                    `fgts` (opcional).
                state:
                  type: string
                  pattern: ^(?:[A-Za-z]{2})?$
                  default: ''
                  description: >-
                    Sigla del estado (UF) de la empresa deudora, p. ej. `SP`
                    (opcional).
                status_type:
                  type: string
                  enum:
                    - ''
                    - in_collection
                    - tax_benefit
                    - guaranteed
                    - suspended_by_court
                    - in_negotiation
                  default: ''
                  description: >-
                    Situación: `in_collection` (en cobro), `tax_benefit`
                    (beneficio fiscal), `guaranteed` (garantizada),
                    `suspended_by_court` (suspendida por decisión judicial),
                    `in_negotiation` (en negociación) (opcional).
                debtor_type:
                  type: string
                  enum:
                    - ''
                    - principal
                    - co_responsible
                    - joint
                  default: ''
                  description: >-
                    Papel de la empresa en la deuda: `principal`,
                    `co_responsible` (corresponsable) o `joint` (solidaria)
                    (opcional).
                in_court:
                  type: string
                  enum:
                    - any
                    - 'yes'
                    - 'no'
                  default: any
                  description: >-
                    `yes` solo deudas en ejecución judicial, `no` solo las que
                    no, `any` ambas.
                amount_min:
                  type: number
                  minimum: 0
                  default: 0
                  description: Monto mínimo de la deuda en reales (opcional).
                amount_max:
                  type: number
                  minimum: 0
                  default: 0
                  description: >-
                    Monto máximo de la deuda en reales; `0` sin límite
                    (opcional).
                page:
                  type: integer
                  minimum: 1
                  maximum: 1000
                  default: 1
                  description: 1-based page number for paginated results.
                per_page:
                  type: integer
                  minimum: 1
                  maximum: 50
                  default: 20
                  description: Resultados por página (1-50).
              additionalProperties: false
            example:
              query: construtora
              in_court: 'yes'
              per_page: 10
      responses:
        '200':
          description: Successful response
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Idempotency-Key:
              $ref: '#/components/headers/Idempotency-Key'
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Sunset:
              $ref: '#/components/headers/Sunset'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            X-Cache:
              $ref: '#/components/headers/X-Cache'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PgfnDebtsSearchResponse'
        '400':
          description: Invalid request body
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Idempotency-Key:
              $ref: '#/components/headers/Idempotency-Key'
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Sunset:
              $ref: '#/components/headers/Sunset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Missing or invalid API key
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Idempotency-Key:
              $ref: '#/components/headers/Idempotency-Key'
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Sunset:
              $ref: '#/components/headers/Sunset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Rate limit exceeded
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Idempotency-Key:
              $ref: '#/components/headers/Idempotency-Key'
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Sunset:
              $ref: '#/components/headers/Sunset'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal error
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Idempotency-Key:
              $ref: '#/components/headers/Idempotency-Key'
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Sunset:
              $ref: '#/components/headers/Sunset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '502':
          description: Upstream source returned an error
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Idempotency-Key:
              $ref: '#/components/headers/Idempotency-Key'
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Sunset:
              $ref: '#/components/headers/Sunset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
        - bearerAuth: []
      externalDocs:
        description: Interactive documentation and examples
        url: https://docs.usecroma.com/guides/brazil/pgfn
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >-
        Optional client-chosen key for this request (any string up to 255
        characters, e.g. a UUID). Every Croma operation is an idempotent lookup:
        repeating a request with the same body returns the same result and
        creates nothing, so retrying after a timeout or network failure is
        always safe. The key is echoed back in the `Idempotency-Key` response
        header so you can correlate a retry with its first attempt. Each attempt
        that reaches the API counts against the rate limit.
      schema:
        type: string
        maxLength: 255
        example: 0f8e9a42-6b7c-4d1e-9a3f-2c5d7e8f9a0b
  headers:
    X-Request-Id:
      description: Unique id for the request (req_…). Include it in support reports.
      schema:
        type: string
    RateLimit-Policy:
      description: >-
        Quota policy for this endpoint as an IETF RateLimit-Policy structured
        field, e.g. `"default";q=100;w=86400` (100 requests per 86400-second
        window per organization). Endpoints with an extra hourly ceiling list
        both policies, e.g. `"webSearch";q=10;w=3600, "default";q=100;w=86400`.
        Present on every response, including 401 and 429.
      schema:
        type: string
        example: '"default";q=100;w=86400'
    Idempotency-Key:
      description: >-
        The `Idempotency-Key` the request carried, echoed back unchanged. Absent
        when the request sent none.
      schema:
        type: string
    Deprecation:
      description: >-
        Present only on an endpoint version scheduled for removal: the date the
        deprecation took effect (RFC 9745). A `Sunset` header and a `Link` with
        `rel="successor-version"` accompany it. Policy:
        https://docs.usecroma.com/versioning
      schema:
        type: string
        example: '@1767225600'
    Sunset:
      description: >-
        Present only on an endpoint version scheduled for removal: the date
        after which it answers 410 (RFC 8594). Announced in the changelog at
        least 90 days ahead.
      schema:
        type: string
        format: date-time
        example: Wed, 01 Apr 2026 00:00:00 GMT
    X-RateLimit-Limit:
      description: Requests allowed in the current window.
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Requests left before you are throttled.
      schema:
        type: integer
    X-RateLimit-Reset:
      description: ISO 8601 timestamp when the window resets.
      schema:
        type: string
        format: date-time
    X-Cache:
      description: HIT or MISS. Cached hits still count against your quota.
      schema:
        type: string
        enum:
          - HIT
          - MISS
    Retry-After:
      description: Seconds to wait before retrying.
      schema:
        type: integer
  schemas:
    PgfnDebtsSearchResponse:
      type: object
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/PgfnDebtsSearchData'
    ApiError:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - type
            - code
            - message
          properties:
            type:
              type: string
              description: >-
                Broad category: invalid_request_error, authentication_error,
                not_found_error, rate_limit_error, upstream_error, api_error.
            code:
              type: string
              description: Machine-readable specific code.
            message:
              type: string
              description: Human-readable explanation, safe to surface in UI.
            param:
              type: string
              description: Field that triggered the error. Present on validation errors.
            details:
              type: object
              description: Free-form structured detail.
    PgfnDebtsSearchData:
      type: object
      properties:
        as_of:
          anyOf:
            - type: string
            - type: 'null'
          description: How current the data in this response is.
        query:
          type: string
        document_number:
          anyOf:
            - type: string
            - type: 'null'
        regime:
          anyOf:
            - type: string
            - type: 'null'
        state:
          anyOf:
            - type: string
            - type: 'null'
        status_type:
          anyOf:
            - type: string
            - type: 'null'
        debtor_type:
          anyOf:
            - type: string
            - type: 'null'
        in_court:
          type: string
        total:
          type: number
          description: Debts matching the filters, across every page.
        page:
          type: number
        per_page:
          type: number
        total_pages:
          type: number
        count:
          type: number
        debts:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: >-
                  The regime, the inscription number and the company's CNPJ,
                  joined by colons: the key.
              regime:
                type: string
                enum:
                  - nao_previdenciario
                  - previdenciario
                  - fgts
                description: >-
                  `nao_previdenciario` (federal taxes and other
                  non-social-security debt), `previdenciario` (social security
                  contributions) or `fgts` (the workers' severance fund).
              inscription_number:
                type: string
                description: >-
                  The inscription's number in the dívida ativa, as PGFN
                  publishes it.
              document_number:
                type: string
                description: The company's CNPJ, 14 characters, no punctuation.
              document:
                type: string
                description: The CNPJ as it is written, `12.345.678/0001-90`.
              cnpj_root:
                type: string
                description: >-
                  The CNPJ's first 8 characters: the same for every
                  establishment of one company.
              debtor_name:
                type: string
                description: The company's name as PGFN records it.
              debtor_type:
                type: string
                enum:
                  - principal
                  - co_responsible
                  - joint
                description: >-
                  The company's role in the debt: `principal`, `co_responsible`
                  or `joint`. An inscription with several debtors has a row for
                  each.
              state:
                anyOf:
                  - type: string
                  - type: 'null'
                description: Two-letter state (UF) of the company.
              responsible_unit:
                anyOf:
                  - type: string
                  - type: 'null'
                description: The PGFN unit in charge, e.g. `3ª REGIÃO`.
              registering_unit:
                anyOf:
                  - type: string
                  - type: 'null'
                description: The unit that registered an FGTS debt.
              collecting_entity:
                type: string
                enum:
                  - pgfn
                  - caixa
                description: 'Who collects the debt: PGFN, or Caixa for part of the FGTS.'
              status_type:
                anyOf:
                  - type: string
                    enum:
                      - in_collection
                      - tax_benefit
                      - guaranteed
                      - suspended_by_court
                      - in_negotiation
                  - type: 'null'
                description: >-
                  `in_collection`, `tax_benefit`, `guaranteed`,
                  `suspended_by_court` or `in_negotiation`.
              status:
                anyOf:
                  - type: string
                  - type: 'null'
                description: The inscription's detailed status, as PGFN words it.
              revenue_type:
                anyOf:
                  - type: string
                  - type: 'null'
                description: >-
                  What the debt is for, as PGFN words it, e.g. `Receita da
                  dívida ativa - PIS`, `Simples Nacional`.
              registered_on:
                anyOf:
                  - type: string
                  - type: 'null'
                description: '`yyyy-mm-dd` the debt was inscribed.'
              in_court:
                type: boolean
                description: true when the debt is being enforced in court (ajuizada).
              amount:
                type: number
                column: number
                description: >-
                  The consolidated amount in reais, with legal charges, as of
                  PGFN's extraction. The whole inscription's amount: repeated on
                  each debtor's row.
              reference_month:
                type: string
                description: '`yyyy-mm`: the month PGFN''s quarterly release refers to.'
            required:
              - id
              - regime
              - inscription_number
              - document_number
              - document
              - cnpj_root
              - debtor_name
              - debtor_type
              - state
              - responsible_unit
              - registering_unit
              - collecting_entity
              - status_type
              - status
              - revenue_type
              - registered_on
              - in_court
              - amount
              - reference_month
      required:
        - as_of
        - query
        - document_number
        - regime
        - state
        - status_type
        - debtor_type
        - in_court
        - total
        - page
        - per_page
        - total_pages
        - count
        - debts
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Use Authorization: Bearer YOUR_API_KEY'

````