# 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`. In staging, voucher `API1234` covers every product; Stripe checkout accepts test card `ACCT-000015`. See [Testing in staging](/testing-in-staging).
5. **Choose the applicant handoff** — either use the portal claim/agreement flow or create a [secure embed session](/reference/post-residency-applications-id-embed-sessions) after every other prerequisite is complete.
6. **Complete and poll** — portal flows call [POST …/submit](/reference/post-residency-applications-id-submit) when `submitReady`; embed flows auto-submit after signed AOC + approved KYC and emit `APPLICATION_SUBMITTED`. 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 supplies applicant details when creating or updating an
  application, but it can never sign the Agreement of Coexistence or read
  identity-verification data from the embed flow. Those actions stay inside the
  cross-origin e-Próspera page. Embed endpoints and `postMessage` events never
  return Veriff URLs, documents, decision details, or applicant PII; the parent
  receives versioned status enums only.
</Callout>

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

* No public webhooks — poll application status (lists support cursor pagination).
* Embed endpoints and `postMessage` never return Veriff URLs, documents,
  decision details, or applicant PII. Applicant details remain valid request
  input to [POST partner/residency\_applications](/reference/post-residency-applications).
* 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
* [Testing in staging](/testing-in-staging) — voucher `API1234` and Stripe test card