> ## 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.

# SUNAT

> Look up Peruvian taxpayer (RUC) information by RUC, identity document, or name.

Resolves Peruvian taxpayer information from SUNAT. Three lookups mirror SUNAT's
own search tabs: by RUC, by identity document, and by name (razón social). The
first two return one taxpayer's full record; the name search returns a list of
matches.

## By RUC

`POST /pe/sunat/ruc/v1`

| Field | Type   | Notes                       |
| ----- | ------ | --------------------------- |
| `ruc` | string | **Required.** 11-digit RUC. |

```bash theme={"dark"}
curl https://api.croma.run/pe/sunat/ruc/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ruc": "20100070970" }'
```

## By document

`POST /pe/sunat/document/v1`

| Field             | Type   | Notes                                                                                   |
| ----------------- | ------ | --------------------------------------------------------------------------------------- |
| `document_type`   | string | One of `dni`, `ce` (carné de extranjería), `passport`, `diplomatic`. Defaults to `dni`. |
| `document_number` | string | **Required.** 6-16 alphanumeric characters.                                             |

```bash theme={"dark"}
curl https://api.croma.run/pe/sunat/document/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "document_type": "dni", "document_number": "74849152" }'
```

## By name

`POST /pe/sunat/name/v1`

| Field  | Type   | Notes                                                 |
| ------ | ------ | ----------------------------------------------------- |
| `name` | string | **Required.** Name or razón social, 3-100 characters. |

```bash theme={"dark"}
curl https://api.croma.run/pe/sunat/name/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "INVERSIONES GENERALES" }'
```

The name search returns up to 30 matches (SUNAT's cap). When `capped` is `true`
the results are incomplete: narrow the query or look the chosen RUC up directly.

## Response

The RUC and document lookups return one taxpayer record.

| Field                                                                            | Notes                                                                                               |
| -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `found`                                                                          | `true` when a taxpayer matches; `false` when SUNAT has none (the other fields are then null/empty). |
| `ruc`                                                                            | The 11-digit RUC.                                                                                   |
| `taxpayer_name`                                                                  | Razón social or full name.                                                                          |
| `taxpayer_type`                                                                  | E.g. `SOCIEDAD ANONIMA`, `PERSONA NATURAL SIN NEGOCIO`.                                             |
| `document_type`, `document_number`                                               | Underlying identity document (natural persons).                                                     |
| `trade_name`                                                                     | Nombre comercial, if any.                                                                           |
| `registration_date`, `activities_start_date`                                     | Fecha de inscripción / inicio de actividades (`dd/mm/yyyy`).                                        |
| `taxpayer_status`                                                                | Estado (e.g. `ACTIVO`, `BAJA DE OFICIO`).                                                           |
| `taxpayer_condition`                                                             | Condición (e.g. `HABIDO`).                                                                          |
| `fiscal_address`                                                                 | Domicilio fiscal.                                                                                   |
| `emission_system`, `accounting_system`                                           | Sistema de emisión / contabilidad.                                                                  |
| `foreign_trade_activity`                                                         | Actividad de comercio exterior.                                                                     |
| `economic_activities`                                                            | List of CIIU activities (principal and secundarias).                                                |
| `payment_vouchers`                                                               | Comprobantes de pago autorizados.                                                                   |
| `electronic_emission_systems`, `electronic_vouchers`, `electronic_emitter_since` | Electronic-invoicing details.                                                                       |
| `ple_affiliated_since`                                                           | Afiliado al PLE desde.                                                                              |
| `registries`                                                                     | Padrones the taxpayer belongs to.                                                                   |

The name lookup returns `query`, `count`, `capped`, and `contributors[]`, each
with `ruc`, `name`, `location`, and `status`.

<Note>
  The old `POST /pe/sunat/taxpayers/v1` (combined RUC/DNI by document length)
  still works but is deprecated. Prefer `/pe/sunat/ruc` or `/pe/sunat/document`.
</Note>

<Note>
  These lookups can take longer than a typical request. They are
  [async jobs](/async-jobs). By default the request waits inline and returns
  `{ data }`, or you can poll / use a `callback_url`.
</Note>

<Card title="Full reference" icon="code" href="/api-reference/overview">
  Schemas, response fields, and an interactive playground.
</Card>