---
title: "Start validation for embedded use"
method: POST
path: "/api/v1/annotations/{annotationID}/start_embedded"
tags: ["Annotation"]
---

# Start validation for embedded use

`POST /api/v1/annotations/{annotationID}/start_embedded`

Start embedded annotation.

Embedded annotation cannot be started by users with admin or organization group admin roles. We strongly recommend
starting embedded annotations by users with `annotator_embedded` [user role](/api/user-role) and permissions
for the given queue only to limit the scope of actions that user is able to perform to required minimum.

Returns object with url that specifies URL to be used in the browser iframe/popup window. URL includes a token that
is valid for this document only for a limited period of time.

## Path parameters

- `annotationID` integer, required

## Request body

- object
  - `return_url` string, uri — URL to redirect to after annotation is confirmed
  - `cancel_url` string, uri — URL to redirect to when annotation is cancelled
  - `delete_url` string, uri — URL to redirect to when annotation is deleted
  - `postpone_url` string, uri — URL to redirect to when annotation is postponed
  - `max_token_lifetime_s` number, float — Duration (in seconds) for which the token will be valid. Default is the [queue's](/api/queue) `session_timeout.`

## Response `200`

Embedded URL created successfully

- object
  - `url` string, uri — Embedded URL with authentication token

## Other responses

- `400` — Invalid input data.
- `401` — The username/password is invalid or token is invalid (e.g. expired).
- `403` — Insufficient permission, missing authentication, invalid CSRF token and similar issue.
- `404` — The specified resource was not found.
- `409` — Conflict
- `413` — Payload too large (especially for files uploaded).
- `429` — Request rate is too high, wait before sending more requests. See [Rate Limiting](/guides/overview#rate-limiting) for more details.
- `500` — Server failure while processing the request.
- `502` — Invalid response from the upstream server.
- `503` — We're temporarily offline for maintenance. Please try again later.
- `504` — Upstream server could not complete the request in time.

---

[API](https://skmtc.dev/rossum/apis/rossum-api.md) · [All operations](https://skmtc.dev/rossum/apis/rossum-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/rossum/rossum-api/revisions/f1b5a910991d/schema)