# Panadata API

> REST API for public registry data in Panama (organizations and natural persons) and Ecuador (organizations only). Search by name or RUC, retrieve detailed records covering corporate governance, assets, trade, legal documents, risk/compliance, and more.

Base URL: `https://api.panadata.net`
Platform: `https://platform.panadata.net`

## Getting started

1. Sign up at https://platform.panadata.net/users/sign_up and confirm your email
2. Create an API key in the dashboard — you'll get a `pk_*` Bearer token
3. Search for an entity, then fetch details with product codes

Free tier: confirmed accounts can query immediately without preloading balance (aggressive rate limits).

## Authentication

All API requests require a Bearer token:

```
Authorization: Bearer pk_XXXXXXXXXXXX
```

## Endpoints

### Health check
`GET /health` — No auth required. Returns `{"status":"ok","service":"panadata-api"}`.

### Search entities
`GET /v4/panama/entidades?nombre={name}` — Search Panama by name (min 3 chars).
`GET /v4/panama/entidades?ruc={ruc}` — Search Panama by RUC.
`GET /v4/ecuador/entidades?nombre={name}` — Same, scoped to Ecuadorian organizations.
`GET /v4/ecuador/entidades?ruc={ruc}` — RUC search for Ecuador organizations (13 digits, ends in `001`).

Returns an array of matching entities with `id`, `nombre`, `ruc`/`cedula`, and `tipo`.

### Get entity detail
`GET /v4/panama/entidades/{id}?include={codes}` — Fetch detailed data (Panama: organizations and natural persons).
`GET /v4/ecuador/entidades/{id}?include={codes}` — Fetch detailed data (Ecuador: organizations only).

The `include` parameter is required and accepts comma-separated product codes. The set of accepted codes varies by jurisdiction — see Coverage below. On an unsupported code the API returns `400` with a `supported_includes` array listing the codes the jurisdiction recognises.

### Request a data refresh (Panama)
`POST /v4/panama/entidades/{id}/update?include={codes}` — Queue an on-demand scrape; result is delivered via webhook or polled with the endpoint below.

### Poll an update request
`GET /v4/update_requests/{update_request_id}` — Returns the status (`pending`/`completed`/`failed`) and result of an update request.

### Ecuador
`GET /v4/ecuador/entidades?nombre={name}` and `GET /v4/ecuador/entidades?ruc={ruc}` to search; `GET /v4/ecuador/entidades/{id}?include={codes}` to fetch detail. Catalog limited today to `CHK-BIN`, `DAT-CORE`, and `DAT-ALL` ($0.85).

### Colombia
`GET /v4/colombia/entidades?nombre={name}` and `GET /v4/colombia/entidades?ruc={ruc}` (numeric param is `ruc` for cross-jurisdiction consistency; in Colombia it searches by NIT). `GET /v4/colombia/entidades/{id}?include={codes}` to fetch detail. Catalog limited to `CHK-BIN` and `DAT-CORE` ($0.10).

## Product codes and pricing

Every request has a **$0.01 base charge**. Product code costs are added on top.

| Code | Cost | What it returns |
|------|------|-----------------|
| CHK-BIN | $0.02 | Binary existence check — id, nombre, ruc/cedula |
| DAT-CORE | $0.15 | Core registry data, contact info, entity events |
| DAT-HOOK | $0.03 | Chronological entity_events feed (max 100). Pull-mode — unrelated to platform webhook delivery |
| DAT-GOV | $0.15 | Directors, board members, legal representatives, government gazette |
| DAT-BIZ | $0.08 | Business licenses, trademarks, trusts |
| DAT-ASSET | $0.25 | Real estate, vehicles, vessels |
| DAT-TRADE | $0.20 | Import/export records and summaries |
| DAT-DOC | $0.06 | Scanned and digital documents |
| DAT-RISK | $0.20 | Delinquent debts, sanctions, court cases |
| DAT-PROC | $0.05 | Public procurement/tenders |
| DAT-NEWS | $0.12 | News mentions (local and global) |
| DAT-MEDIA | $0.12 | News (local and global) plus entity_events feed |
| DAT-LEGAL | $0.10 | Migration and work permits |
| DAT-CGR | $0.08 | Comptroller documents and public payroll |
| DAT-IP | $0.03 | Trademarks |
| DAT-LABOR | $0.15 | Migration, work permits, public payroll |
| DAT-SCREEN | $0.40 | International sanctions and PEP matches |
| DAT-ALL | $1.81 | All available data levels (Panama). In Ecuador, DAT-ALL is $0.85 for the 14-level catalog (organizations only). |

Smart resolution: overlapping codes are deduplicated — you only pay for non-redundant data.

Ecuador accepts only `CHK-BIN`, `DAT-CORE`, and `DAT-ALL`. The other codes return `400 unknown product code(s)` on `/v4/ecuador/entidades/{id}`. The reduced DAT-ALL price reflects the smaller catalog wired today.

## Example workflow

```bash
# 1. Search by name (Panama)
curl -H "Authorization: Bearer pk_XXX" \
  "https://api.panadata.net/v4/panama/entidades?nombre=copa+airlines"

# 2. Get details with product codes (Panama)
curl -H "Authorization: Bearer pk_XXX" \
  "https://api.panadata.net/v4/panama/entidades/12345?include=DAT-CORE,DAT-GOV"

# 3. Same flow for Ecuador (organizations only)
curl -H "Authorization: Bearer pk_XXX" \
  "https://api.panadata.net/v4/ecuador/entidades?ruc=1768040920001"

curl -H "Authorization: Bearer pk_XXX" \
  "https://api.panadata.net/v4/ecuador/entidades/52015398?include=DAT-ALL"
```

## Coverage

- **Panama** (full) — 28 data sources, 34 data levels, 17 product codes. Organizations and natural persons.
- **Ecuador** (initial — organizations only) — 8 data sources, 14 data levels, 3 product codes (`CHK-BIN`, `DAT-CORE`, `DAT-ALL`). Natural persons not part of the public catalog (LOPDP).
- **Colombia** — upcoming.

## Documentation

- [Getting started](https://platform.panadata.net/docs/empezar)
- [Authentication guide](https://platform.panadata.net/docs/guias/autenticacion)
- [First query guide](https://platform.panadata.net/docs/guias/primera-consulta)
- [Include parameter guide](https://platform.panadata.net/docs/guias/include-parameter)
- [Sandbox vs API](https://platform.panadata.net/docs/guias/sandbox-vs-api)
- [Error handling](https://platform.panadata.net/docs/guias/errores)
- [Async updates and webhooks](https://platform.panadata.net/docs/guias/webhooks)
- [API reference (OpenAPI)](https://platform.panadata.net/docs/referencia)
- [Jurisdictions](https://platform.panadata.net/docs/conceptos/jurisdicciones)
- [Data sources](https://platform.panadata.net/docs/conceptos/fuentes-de-datos)
- [Data levels](https://platform.panadata.net/docs/conceptos/niveles-de-datos)
- [Product codes](https://platform.panadata.net/docs/conceptos/codigos-de-producto)
- [Billing](https://platform.panadata.net/docs/conceptos/facturacion)

## Machine-readable specs

- [OpenAPI 3.0 (Spanish)](https://platform.panadata.net/openapi.yml)
- [OpenAPI 3.0 (English)](https://platform.panadata.net/openapi.en.yml)
- [AI plugin manifest](https://platform.panadata.net/.well-known/ai-plugin.json)
- [Full docs as a single markdown file](https://platform.panadata.net/llms-full.txt)

Every docs page is also available as markdown by appending `.md` to its URL — e.g. `https://platform.panadata.net/docs/conceptos/codigos-de-producto.md`.