---
title: "Update session"
slug: "v1sessionsid-2"
updated: 2026-04-24T06:47:50Z
published: 2026-04-24T06:47:50Z
---

> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.veriff.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update session

Patch/v1/sessions/{id}

### Updates verification session status to trigger session processing

#### When to use this endpoint

- Use this endpoint to submit a verification session for processing
after all required media and data have been uploaded

Common use cases include:

- Finalizing session after manual media upload via API
- Triggering verification review when using headless integration
- Completing sessions where end-user completed verification outside the standard flow

#### Request body content

- The request body must contain a `verification` object with `status` field set to `submitted`
- This is currently the only supported status update via this endpoint

#### Implementation notes

- Session must be in `created` or `started` status before calling this endpoint
- Session cannot be updated after it has been submitted
- This endpoint requires session-level [HMAC signature](https://devdocs.veriff.com/docs/hmac-authentication-and-endpoint-security#public-api-v1) authentication
- All required media must be uploaded before submitting the session. If you try to upload media after you have submitted the session, you may encounter the 409 - conflict error.
- Always ensure that you use the correct API URL to send requests. See the [API URL section](https://devdocs.veriff.com/apidocs/veriff-public-api-guides#api-url) for more info
- The order of parameters in the real API response can differ from the order you see in this documentation. This is expected and part of the [Backwards compatible changes](https://devdocs.veriff.com/apidocs/veriff-public-api-guides#backwards-compatible-changes) requirements

Header parametersX-AUTH-CLIENTstringRequired

Your integration's API key (occasionally referred to as the "Token", "API public key" or "Publishable key"). Required for all API requests.

You can find your API key in the Veriff Customer Portal > Settings > API keys.

Exampleyour_api_key
X-HMAC-SIGNATUREstringRequired

Request body signed with the shared secret key. Required to authenticate the request sender.

Content-TypestringRequiredExampleapplication/json

Path parametersidstring (uuid) Required

Verification session ID.

Example123e4567-e89b-12d3-a456-426614174000

Body parameters

Session data

<select class='api-response-data' aria-label='Media type'><option value='ed53208e-7d6a-42e3-ae87-b6f907768213'>application/json</option>
</select><select class='select-example' aria-label='Media type'><option value='8aed4acf-c215-4bad-b615-a9d2708940e6'>submit_session</option>
</select>submit_session

Standard request to submit a verification session after all media has been uploaded

```json
{
  "verification": {
    "status": "submitted"
  }
}
```

Expand Allobject  verificationobject  Required

Verification object.

statusstring    Required

Status of a verification session, always `submitted`.

Valid values[
  "submitted"
]Examplesubmitted

Responses200

Session is patched

HeadersContent-TypestringResponse content type.
X-AUTH-CLIENTstringAPI key echoed back in response.
X-HMAC-SIGNATUREstringResponse body signed with the shared secret key. Required to authenticate the response sender.
<select class='api-response-data' aria-label='Media type'><option value='9654221c-e911-44a8-9c94-e36804d91ee8'>application/json</option>
</select><select class='select-example' aria-label='Media type'><option value='7fea9561-18ed-4cee-951c-3b063eacd130'>session_submitted</option>
</select>session_submitted

Session status updated to submitted and ready for verification processing

```json
{
  "status": "success",
  "verification": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "url": "https://alchemy.veriff.com/v/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uX2lkIjoiZmQ",
    "vendorData": "1234567890",
    "host": "https://alchemy.veriff.com",
    "status": "submitted",
    "sessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
```

Expand Allobject  statusstring    

API request status.

Examplesuccess
verificationobject  

Verification object.

idstring  (uuid)    

UUID v4 which identifies the verification session.

Example123e4567-e89b-12d3-a456-426614174000
urlstring    

URL for the verification session. Combination of `host` and `sessionToken`.

Examplehttps://exampleURL.com/v/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uX2lkIjoiZmQ
vendorDatastring   | null  

The unique identifier that you created for your end-user. It can be max 1,000 characters long and contain only non-semantic data that can not be resolved or used outside your systems or environments. Veriff returns it unmodified in webhooks and API response payloads, or as `null` if not provided.

Example1234567890
hoststring    

Host URI for the verification session.

Examplehttps://exampleURL.com
statusstring    

Verification session status after update.

Valid values[
  "submitted"
]Examplesubmitted
sessionTokenstring    

Session-specific token of the verification.

ExampleeyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

400

Bad request

HeadersContent-TypestringResponse content type.
X-AUTH-CLIENTstringAPI key echoed back in response.
X-HMAC-SIGNATUREstringResponse body signed with the shared secret key. Required to authenticate the response sender.
<select class='api-response-data' aria-label='Media type'><option value='8b77fe9d-5dc6-4585-a921-1d93948dd77a'>application/json</option>
</select><select class='select-example' aria-label='Media type'><option value='517420c8-9692-44b2-b487-3918dfaa6ca2'>invalid_status</option>
<option value='d6294eb0-3d1c-42d1-a3c1-f46a427add45'>session_already_submitted</option>
</select>invalid_status

Request contains invalid or unsupported status value

```json
{
  "status": "fail",
  "code": "1101",
  "message": "Validation failed"
}
```

session_already_submitted

Attempt to update a session that has already been submitted

```json
{
  "status": "fail",
  "code": "1101",
  "message": "Session has already been submitted"
}
```

object  statusstring    Valid values[
  "fail"
]Examplefail
codestring    Example1101
messagestring    ExampleValidation failed

401

Unauthorized

HeadersContent-TypestringResponse content type.
X-AUTH-CLIENTstringAPI key echoed back in response.
X-HMAC-SIGNATUREstringResponse body signed with the shared secret key. Required to authenticate the response sender.
<select class='api-response-data' aria-label='Media type'><option value='783f3a19-b117-4882-af24-bcacfe0d4589'>application/json</option>
</select><select class='select-example' aria-label='Media type'><option value='f16ffe1f-db75-4007-8f06-789039fbea04'>missing_api_key</option>
<option value='47a9832a-f7a4-45a4-81f6-deec8d949186'>invalid_hmac</option>
</select>missing_api_key

x-auth-client header not provided

```json
{
  "status": "fail",
  "code": "1101",
  "message": "Mandatory X-AUTH-CLIENT header containing the API key is missing from the request."
}
```

invalid_hmac

x-hmac-signature validation failed

```json
{
  "status": "fail",
  "code": "1812",
  "message": "Invalid HMAC signature"
}
```

object  statusstring    Valid values[
  "fail"
]Examplefail
codestring    Example1101
messagestring    ExampleMandatory X-AUTH-CLIENT header containing the API key is missing from the request.

404

Session not found

HeadersContent-TypestringResponse content type.
X-AUTH-CLIENTstringAPI key echoed back in response.
X-HMAC-SIGNATUREstringResponse body signed with the shared secret key. Required to authenticate the response sender.
<select class='api-response-data' aria-label='Media type'><option value='fbc5d11e-49d1-4d9e-9df0-369c32cf7ff3'>application/json</option>
</select><select class='select-example' aria-label='Media type'><option value='1be38f8c-9ae4-4e13-8430-6c8ca4ba205f'>session_not_found</option>
</select>session_not_found

No session exists with the provided session ID.

```json
{
  "status": "fail",
  "code": "1101",
  "message": "Resource not found"
}
```

object  statusstring    Valid values[
  "fail"
]Examplefail
codestring    Example1101
messagestring    ExampleResource not found

500

Internal server error

HeadersContent-TypestringResponse content type.
X-AUTH-CLIENTstringAPI key echoed back in response.
X-HMAC-SIGNATUREstringResponse body signed with the shared secret key. Required to authenticate the response sender.
<select class='api-response-data' aria-label='Media type'><option value='50e9364f-ce73-4cb6-8d8b-f5fba3db2d03'>application/json</option>
</select><select class='select-example' aria-label='Media type'><option value='a275048a-27ee-43b6-9da4-e7d5d8da1ac7'>server_error</option>
</select>server_error

Unexpected error occurred while processing the request

```json
{
  "status": "fail",
  "code": "1101",
  "message": "Something went wrong"
}
```

object  statusstring    Valid values[
  "fail"
]Examplefail
codestring    Example1101
messagestring    ExampleSomething went wrong

		
			

<title style="font-size:15px;">Document Versioning</title>

**Changelog**

| Date | Description |
| --- | --- |
| Apr 24, 2026 | Headers capitalization harmonized |
| Mar 8, 2026 | Documentation updated: parent categories rearranged, intro section expanded, request and response examples added |
| Oct 2, 2025 | `vrf-` headers removed from response headers |
| Aug 6, 2025 | Response headers added |
| Mar 12, 2025 | Documentation published |