# Verify residents and entities as a compliance vendor (/use-cases/verify-residents)

Confirm Resident Permit Numbers and look up registry records in real time for KYC, AML, and background-check workflows.



You run a KYC/AML product, a background-check service, or a compliance desk, and you need to confirm that a Próspera resident or legal entity is real and in good standing.

**Credential:** a standard API key (`sk-`) is enough for registry-level checks. Person-level reads (residency status, ID verification) additionally require an [Agent Key](/agent-keys) (`ak-`) delegated by the person, or an [OAuth](/oauth-overview) token with their consent.

## 1. Verify an RPN [#1-verify-an-rpn]

Given a 14-digit Resident Permit Number (entities start with `8`, natural persons with `9`), confirm it exists and is active:

```bash
curl -s -X POST https://portal.eprospera.com/api/v1/verify_rpn \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{"rpn": "80000000000012"}'
```

```json
{ "result": "found_legal_entity", "active": true }
```

`result` is one of `found_legal_entity`, `found_natural_person`, or `not_found`. This endpoint is rate-limited to 5,000/day and 50/minute per key — cache results where your compliance policy allows. See [POST verify\_rpn](/reference/post-verify-rpn).

## 2. Resolve a name to a registry record [#2-resolve-a-name-to-a-registry-record]

When you have a company name instead of an RPN, search the public legal-entity registry:

```bash
curl -s -X POST https://portal.eprospera.com/api/v1/registries/legal_entities/search \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{"query": "Acme Holdings"}'
```

Each match includes the entity `id`, `name`, `extension`, and `residentPermitNumber`. See [POST registries/legal\_entities/search](/reference/post-search-entities).

## 3. Pull entity details and documents [#3-pull-entity-details-and-documents]

With the entity `id`, fetch the full record and its certificates and filings:

* [GET legal\_entities/\{id}](/reference/get-legal-entities-id)
* [GET legal\_entities/\{id}/documents](/reference/get-legal-entities-id-documents)

<Callout title="Agent-key visibility" type="warn">
  With an Agent Key, `GET /legal_entities/{id}` only returns entities created
  via the API. Registry **search** is the broad lookup across all registered
  entities — resolve through search first.
</Callout>

## 4. Person-level KYC (requires delegation) [#4-person-level-kyc-requires-delegation]

To read a natural person's residency status or ID-verification state, the person must delegate access — there is no vendor-wide lookup of personal data. Two options:

* **Agent Key** issued by the person with `agent:person.details.read`, `agent:person.residency.read`, `agent:person.id_verification.read` — see [Agent recipes → account-holder profile](/agent-recipes).
* **OAuth** consent flow with the `eprospera:person.*` scopes — see [Sign in with e-Próspera](/use-cases/sign-in-with-eprospera).

Endpoints: [natural person](/reference/oauth-get-natural-person) · [residency](/reference/oauth-get-natural-person-residency) · [ID verification](/reference/oauth-get-id-verification).

## What this API does not do [#what-this-api-does-not-do]

* No public webhooks — re-verify on your own schedule instead of waiting for pushes.
* No bulk export of the registry; query per entity.
* No personal-data lookup without the person's delegation or consent.

## Next steps [#next-steps]

* [Getting started](/getting-started) — create your API key
* [Conventions](/conventions) — error envelope, status codes, rate limits
* [Testing in staging](/testing-in-staging)