---
title: "Create an embed session"
method: POST
path: "/v1/embed/session"
tags: ["Embed"]
---

# Create an embed session

`POST /v1/embed/session`

## Request

- Base URL: `https://api.signvoy.com`
- URL: `https://api.signvoy.com/v1/embed/session`
- Auth: one of:
  - API key in header `X-Workspace-Id`
  - HTTP bearer

Mints a scoped, short-lived signing URL for a specific document recipient. Pass the returned `url` to an `<iframe src={url}>` or to the `@signvoy/react` `<SignvoyEmbed url={url} />` component. The document must be in `sent` state and the recipient must be `pending`.

## Request body

- CreateEmbedSessionDto
  - `documentId` string, uuid, required: UUID of the document whose signing session to embed
  - `documentRecipientId` string, uuid, required: UUID of the specific recipient whose signing view to embed
  - `expiresInSeconds` integer: How long (seconds) the returned signing URL should remain valid. Defaults to 1 hour. Maximum is 24 hours.

## Response `201`

Embed session created — includes the signing URL

- EmbedSessionResponseDto
  - `url` string, uri, required: Scoped signing URL for the specified recipient. Embed this in an <iframe> or pass it to the @signvoy/react <SignvoyEmbed /> component. The URL is single-use and expires after the requested window.
  - `expiresAt` string, date-time, required: ISO 8601 timestamp when this session URL expires
  - `documentId` string, uuid, required: Document ID this session belongs to
  - `documentRecipientId` string, uuid, required: Recipient ID this session was issued for

## Other responses

- `400`: Document not in 'sent' state or recipient already signed
- `403`: Document does not belong to this workspace
- `404`: Document or recipient not found

---

[API](https://skmtc.dev/signvoy/apis/signvoy-api.md) · [All operations](https://skmtc.dev/signvoy/apis/signvoy-api/llms.txt) · [OpenAPI document](https://skmtc.dev/signvoy/apis/signvoy-api/revisions/003cabc7cfe2?raw)