Partner Keys

The actors have separate responsibilities: the partner manages application data, private proof uploads, and payment. The applicant personally accepts the Agreement of Coexistence (AOC) and completes Veriff either in the eProspera portal or in the cross-origin eProspera embed. Partners cannot submit a signature, receive a Veriff URL, or read Veriff documents or decisions through the Partner API.

This page is the API contract. Provisioning, origins, key rotation, and the pre-production checklist are in Partner onboarding. The applicant-facing iframe is in Embedded agreement and identity verification.

Base URL

For the legacy staging hostname and OAuth discovery behavior, see Testing in staging.

Provisioning and key lifecycle

Partner integrations and keys are issued by eProspera administrators. They are not self-service. See Partner onboarding for what to send and how keys rotate.

• The raw key is displayed once. eProspera stores only its SHA-256 hash.
• Keys expire after 90 days.
• Issuing a replacement key shortens older active keys to a maximum seven-day overlap.
• Scopes are fixed at issuance. Changing scopes means issuing a replacement key.
• A key can be revoked immediately. Integrations can be suspended or revoked independently.
• Authentication is rejected when the key is expired or revoked, the integration is not active, or its legal entity is dissolved.
• Redirect and checkout return URLs must use an HTTPS origin approved on the integration. Embed parent origins use a separate approved list.

Send the key on every request:

Authorization: Bearer pk-...

Authentication failures return one of these bodies: Missing API key (401), Invalid API key (401, also used for expired and revoked keys and inactive integrations), Insufficient permissions (403), and Too many requests (429).

Scopes

There is no API scope for signing the Agreement of Coexistence. Applicant consent always occurs in an eProspera-hosted origin, including when that origin is framed by an approved partner page.

Endpoints

Cross-partner reads and mutations return 404 so the existence of another integration's resources is not disclosed.

The documents endpoint returns the Agreement of Coexistence version the applicant accepted, with its template PDF, and, once the residency exists, the applicant's signed agreement and policy documents. Documents are classified by stable slug only; it never returns identity-verification artifacts, tax documents, or other uploads.

The Personal and applicant documents guide covers complete responses, acceptance versus signed PDFs, delayed generation, download handling, and the exact residency-matching rules.

Secure application flow

Partner and applicant responsibilities

1. Create a Draft with POST /partner/residency_applications and a unique Idempotency-Key. eProspera sends the applicant a single-use account-claim link that expires after 24 hours.
2. Choose one proof path: upload a document using the new application ID, or send applicationData.personalDetails.proofOfAddressSwornStatement inline on create/PATCH.
3. For the upload path only, attach the returned opaque proofOfAddressUploadId with PATCH /partner/residency_applications/{id} and the latest expectedVersion. The sworn-statement path skips upload and attachment.
4. Pay with a checkout session or voucher. Each payment request requires its own Idempotency-Key. In staging, voucher API1234 applies to every product; hosted Stripe checkout accepts test card ACCT-000015. See Testing in staging.
5. Instruct the applicant to use the claim email and log in to eProspera. Fetch the application again after the final PATCH, then send that applicant the current nextSteps.agreementUrl.
6. The agreement URL contains a 30-minute, single-use token. eProspera requires the applicant's Auth0 login and verifies that the logged-in subject owns the application. During login, the bearer is held server-side behind a short-lived, single-use opaque continuation rather than copied into login or returnTo URLs. A different user receives 404, and admin impersonation is not accepted as applicant identity.
7. After acceptance, fetch the application again: acceptance consumes the link and increments version. Use the refreshed version for any later PATCH. When the application carried an approved redirectUrl, the applicant is returned to it after accepting.
8. The logged-in applicant starts and completes Veriff in the authenticated eProspera portal. The partner sees only applicantPortalAccess, nextSteps.verificationRequired, and nextSteps.submitReady.
9. Submit the application after nextSteps.submitReady becomes true.

The hosted agreement page selects the applicable AOC server-side. Acceptance records the agreement ID and version, SHA-256 hashes of its content and the legally relevant application data, the authenticated applicant's Auth0 subject, signer name, signature image, timestamp, IP address, user agent, and access-token ID. Any PATCH that changes applicationData invalidates the current acceptance and returns a new agreementUrl; submission also rejects consent if application data changed through another path. Bearer-only acceptances without a matching authenticated signer are not valid for submission.

Submission requires current agreement acceptance, proof of address, a paid invoice, and approved identity verification. AOC acceptance and payment endpoints never submit the application; submission occurs only through /submit with partner:person.application.submit.

What the applicant receives

On creation, an applicant without an existing eProspera password receives an email titled Claim your ePróspera account with a Set Password button. The link is single-use and expires after 24 hours; if it expires, the applicant asks eProspera support for a new one. Applicants who already have an eProspera account receive no email and log in with their existing credentials; in that case applicantPortalAccess.claimLinkSent is false on the create response. A PATCH that changes the applicant email sends a new claim email to the new address under the same rule.

Embedded applicant flow

The embed is an alternative to the portal handoff. Your page frames an eProspera-hosted iframe in which the applicant signs the AOC and completes Veriff without first claiming a portal account. Your page receives status-only postMessage events, and eProspera submits the application automatically when both steps complete. Session issuance requires partner:person.embed_session.create and an application whose data, proof of address, and payment are complete.

The full guide, including origins, activation, the event contract, expiry, and the error catalog, is Embedded agreement and identity verification.

Create and update contracts

Create requests require Idempotency-Key:

curl -X POST https://portal.eprospera.com/api/v1/partner/residency_applications \
  -H "Authorization: Bearer pk-REDACTED" \
  -H "Idempotency-Key: application-ada-20260716" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationData": {
      "residencyType": "e_resident",
      "personalDetails": {
        "givenName": "Ada",
        "surname": "Lovelace",
        "email": "applicant@example.com",
        "dateOfBirth": "1990-12-10",
        "sex": "female",
        "countryOfBirth": "GB",
        "citizenships": ["GB"],
        "alternateNamesAttestation": false,
        "criminalBackgroundAttestation": true,
        "address": {
          "line1": "123 Main St",
          "city": "London",
          "postalCode": "SW1A 1AA",
          "country": "GB"
        },
        "phoneNumber": "+447700900123"
      }
    },
    "redirectUrl": "https://partner.example/return"
  }'

An update sends the full application DTO plus the response's latest version:

{
  "expectedVersion": 3,
  "applicationData": {
    "residencyType": "e_resident",
    "personalDetails": {
      "givenName": "Ada",
      "surname": "Lovelace",
      "email": "applicant@example.com",
      "dateOfBirth": "1990-12-10",
      "sex": "female",
      "countryOfBirth": "GB",
      "citizenships": ["GB"],
      "alternateNamesAttestation": false,
      "criminalBackgroundAttestation": true,
      "proofOfAddressUploadId": "12345678-abcd-4abc-8abc-123456789012",
      "address": {
        "line1": "123 Main St",
        "city": "London",
        "postalCode": "SW1A 1AA",
        "country": "GB"
      },
      "phoneNumber": "+447700900123"
    }
  }
}

Once an invoice is paid, the residency type and applicant email are locked. A stale expectedVersion returns 409 with currentVersion.

Residency types

Current prices appear on the invoice created for the application and on the hosted checkout page.

Field formats

Referral codes

referralCode on create or PATCH attributes the applicant to an existing eProspera referral code. Attribution is permanent and only possible for newly created applicants.

Create and update errors

Proof-of-address uploads

POST /api/v1/uploads/proof_of_address is multipart/form-data with two fields: applicationId (a Draft owned by your integration) and file. Accepted types are PDF, JPEG, and PNG. The declared MIME type must match the file's actual bytes, and the maximum size is 4.5 MB. The response is { "data": { "id", "applicationId", "contentType", "size" } } and never contains a URL. Attach the id through PATCH as proofOfAddressUploadId.

GET /api/v1/uploads/proof_of_address/{uploadId} streams the file back with its original Content-Type, Content-Disposition: inline, and Cache-Control: private, no-store.

Payment

Both payment endpoints require the application to be in Draft with proof of address present, and each call requires its own Idempotency-Key. Payment never submits the application.

Hosted checkout

Send exactly one of paymentProvider or paymentMethod, plus a redirectUrl on an approved redirect origin and an optional email for the receipt.

The response is { "data": { "url": "..." }, "invoiceId": "..." }. Send the applicant or payer to data.url. Stripe returns the payer to redirectUrl?success=true after payment and to redirectUrl unchanged on cancel. Payment is confirmed asynchronously: poll the application until nextSteps.paymentRequired is false rather than trusting the redirect.

Vouchers

POST .../pay/voucher with { "voucherCode": "..." } applies a voucher that must cover the full invoice. On success the response is { "data": <application> }, with nextSteps.paymentRequired already false. Errors carry a machine-readable code:

Submission

POST .../submit takes no body and no Idempotency-Key. It moves the application from Draft to Pending Review and returns the application. It fails with 400 and one of these messages while a prerequisite is missing: Please accept the current Agreement of Coexistence before continuing., Please provide proof of address before continuing., a payment message containing invoice, or Please complete identity verification before continuing. An already submitted application returns 400 Residency application is not in draft status.

Response fields

Application responses include:

nextSteps.agreementUrl is ephemeral. Fetch the application after every PATCH and after AOC acceptance. Do not cache or reuse an older URL or version.

applicantPortalAccess.claimLinkSent and claimLinkSentAt describe whether the current mutation enqueued a claim email. GET requests do not send email and therefore return false and null for those fields.

Status lifecycle

Applications move Draft → Pending Review → Approved or Rejected. After submission, poll GET /partner/residency_applications/{id} until statusId leaves Pending Review; residentPermitNumber is populated on approval. eProspera reviews submitted applications manually, so allow for business-day turnaround in production.

Application lists use cursor pagination and return the newest applications first:

GET /api/v1/partner/residency_applications?limit=50&cursor=<application-id>

limit defaults to 50 and cannot exceed 100. The response contains pagination.nextCursor, or null on the final page. Invalid values return 400 Invalid pagination parameters.

Idempotency

Application creation, checkout creation, and voucher payment require an Idempotency-Key containing 8–128 URL-safe characters. Records are retained for 24 hours per integration and route.

• An identical completed request replays the stored response with Idempotency-Replayed: true.
• Reusing a key with different input returns 409 Idempotency-Key was already used with a different request body.
• A duplicate received while the original is processing returns 409.
• A missing or malformed key returns 400 Idempotency-Key is required and must contain 8-128 URL-safe characters.

Rate limits

Limits are enforced by both API key and integration:

Invalid credentials are limited to 20 attempts per minute per source IP. A throttled request returns 429 and a Retry-After header.

Errors

Every successful action, denied scoped action, throttling decision, inactive-key attempt, and admin key lifecycle change is durably audited without storing raw credentials.