# Onboard residents as a relocation partner (/use-cases/residency-partner)

Submit and manage natural-person residency applications for your clients with a Partner Key — drafts, documents, payment, and submission.



You run a relocation service, an immigration consultancy, or a digital-nomad platform, and you onboard clients into Próspera residency on their behalf.

**Credential:** a Partner Key (`pk-`), issued by the e-Próspera team to approved organizations — [Partner Keys](/partner-keys) covers issuance, 90-day expiry, security responsibilities, and rate limits. This surface is separate from Agent Keys: it is organization-scoped, not person-delegated.

## The flow [#the-flow]

1. **Create a Draft** — [POST partner/residency\_applications](/reference/post-residency-applications) with the applicant's personal details and a unique `Idempotency-Key`. e-Próspera emails the applicant a single-use account-claim link (24-hour expiry).
2. **Complete the data** — [PATCH partner/residency\_applications/\{id}](/reference/patch-residency-applications-id) with `expectedVersion` for optimistic concurrency.
3. **Attach proof of address** — [upload the document](/reference/post-uploads-proof-of-address) to get an opaque `proofOfAddressUploadId`, then attach it via PATCH. (The sworn-statement path skips the upload.)
4. **Pay** — [hosted checkout](/reference/post-residency-applications-id-checkout-session) or [voucher](/reference/post-residency-applications-id-pay-voucher), each with its own `Idempotency-Key`.
5. **Hand off to the applicant** — the applicant claims their account, signs the Agreement of Coexistence at `nextSteps.agreementUrl`, and completes identity verification in their own session.
6. **Submit and poll** — once `nextSteps.submitReady` is `true`, call [POST …/submit](/reference/post-residency-applications-id-submit), then poll [GET …/\{id}](/reference/get-residency-applications-id) until `Approved`/`Rejected`.

The full nine-step secure flow — including which fields each scope unlocks and the per-endpoint rate limits — is in [Partner Keys](/partner-keys).

<Callout title="What partners cannot do" type="warn">
  Your organization can never sign the Agreement of Coexistence or start/read
  identity verification (Veriff) for an applicant — those happen only in the
  applicant's own authenticated e-Próspera session. Your integration prepares
  everything, then reads `nextSteps` to know when the applicant has done their
  part.
</Callout>

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

* No public webhooks — poll application status (lists support cursor pagination).
* No Veriff initiation or results via Partner Keys.
* Partner Keys expire after 90 days — build rotation into your ops calendar.

## Next steps [#next-steps]

* [Partner Keys](/partner-keys) — the complete integration contract
* [Uploads reference](/reference/post-uploads-proof-of-address) — private document handling
* [Conventions](/conventions) — idempotency, errors, pagination