---
title: "Create a secure agreement and KYC embed session"
method: POST
path: "/api/v1/partner/residency_applications/{id}/embed_sessions"
tags: ["Partner residency applications"]
---

# Create a secure agreement and KYC embed session

`POST /api/v1/partner/residency_applications/{id}/embed_sessions`

Requires `partner:person.embed_session.create`. The application must be partner-owned, complete except for agreement/KYC, and paid. The one-time URL is bound to the parent-held PKCE verifier and may only be framed by the selected allow-listed origin. Issuance is not idempotent: retrying this operation creates a replacement link and revokes any previously active embed session for the application.

## Path parameters

- `id` string, uuid, required

## Request body

- PartnerEmbedSessionRequest
  - `parentOrigin` string, uri, required
  - `codeChallenge` string, required
  - `codeChallengeMethod` 'S256', required
  - `locale` 'en' | 'es'

## Response `201`

Single-use embed session created.

- object — Successful response.
  - `data` PartnerEmbedSessionResponse, required
    - `sessionId` string, uuid, required
    - `embedUrl` string, uri, required
    - `tokenExpiresAt` string, date-time, required
    - `flowExpiresAt` string, date-time, required

## Other responses

- `400` — Validation error or precondition failure.
- `401` — Missing or invalid credential.
- `403` — Credential lacks the required scope (Agent Key) or insufficient OAuth scope.
- `404` — Resource does not exist or is invisible to the caller. The two are intentionally indistinguishable.
- `409` — The application is not ready for embed issuance, or its state changed concurrently.
- `429` — Partner API rate limit exceeded.
- `500` — Server error.
- `503` — Partner embed sessions are disabled in this environment.

---

[API](https://skmtc.dev/eprospera/apis/e-pro-spera-api.md) · [All operations](https://skmtc.dev/eprospera/apis/e-pro-spera-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/eprospera/e-pro-spera-api/revisions/9ecdd3ca5a8c/schema)