Onboard residents as a relocation partner

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

1. Create a Draft — POST partner/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} with expectedVersion for optimistic concurrency.
3. Attach proof of address — upload the document to get an opaque proofOfAddressUploadId, then attach it via PATCH. (The sworn-statement path skips the upload.)
4. Pay — hosted checkout or 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.
5. Choose the applicant handoff — either use the portal claim/agreement flow or create a secure embed session after every other prerequisite is complete.
6. Complete and poll — portal flows call POST …/submit when submitReady; embed flows auto-submit after signed AOC + approved KYC and emit APPLICATION_SUBMITTED. Poll GET …/{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.

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.
• Partner Keys expire after 90 days — build rotation into your ops calendar.

Next steps

• Partner Keys — the complete integration contract
• Uploads reference — private document handling
• Conventions — idempotency, errors, pagination
• Testing in staging — voucher API1234 and Stripe test card