Update session

  • Updated on Mar 9, 2026
  • Published on Mar 8, 2026
Prev Next
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 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 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 requirements
Header parameters
x-auth-client
stringRequired

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-signature
stringRequired

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

content-type
stringRequired
Exampleapplication/json
Path parameters
id
string (uuid) Required

Verification session ID.

Example123e4567-e89b-12d3-a456-426614174000
Body parameters

Session data

submit_session

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

{
  "verification": {
    "status": "submitted"
  }
}
Expand All
object
verification
object Required

Verification object.

status
string Required

Status of a verification session, always submitted.

Valid values[ "submitted" ]
Examplesubmitted
Responses
200

Session is patched

Headers
content-type
string
Response content type.
x-auth-client
string
API key echoed back in response.
x-hmac-signature
string
Response body signed with the shared secret key. Required to authenticate the response sender.
session_submitted

Session status updated to submitted and ready for verification processing

{
  "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 All
object
status
string

API request status.

Examplesuccess
verification
object

Verification object.

id
string (uuid)

UUID v4 which identifies the verification session.

Example123e4567-e89b-12d3-a456-426614174000
url
string

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

Examplehttps://exampleURL.com/v/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uX2lkIjoiZmQ
vendorData
string | 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
host
string

Host URI for the verification session.

Examplehttps://exampleURL.com
status
string

Verification session status after update.

Valid values[ "submitted" ]
Examplesubmitted
sessionToken
string

Session-specific token of the verification.

ExampleeyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
400

Bad request

Headers
content-type
string
Response content type.
x-auth-client
string
API key echoed back in response.
x-hmac-signature
string
Response body signed with the shared secret key. Required to authenticate the response sender.
invalid_status

Request contains invalid or unsupported status value

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

Attempt to update a session that has already been submitted

{
  "status": "fail",
  "code": "1101",
  "message": "Session has already been submitted"
}
object
status
string
Valid values[ "fail" ]
Examplefail
code
string
Example1101
message
string
ExampleValidation failed
401

Unauthorized

Headers
content-type
string
Response content type.
x-auth-client
string
API key echoed back in response.
x-hmac-signature
string
Response body signed with the shared secret key. Required to authenticate the response sender.
missing_api_key

x-auth-client header not provided

{
  "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

{
  "status": "fail",
  "code": "1812",
  "message": "Invalid HMAC signature"
}
object
status
string
Valid values[ "fail" ]
Examplefail
code
string
Example1101
message
string
ExampleMandatory X-AUTH-CLIENT header containing the API key is missing from the request.
404

Session not found

Headers
content-type
string
Response content type.
x-auth-client
string
API key echoed back in response.
x-hmac-signature
string
Response body signed with the shared secret key. Required to authenticate the response sender.
session_not_found

No session exists with the provided id

{
  "status": "fail",
  "code": "1101",
  "message": "Resource not found"
}
object
status
string
Valid values[ "fail" ]
Examplefail
code
string
Example1101
message
string
ExampleResource not found
500

Internal server error

Headers
content-type
string
Response content type.
x-auth-client
string
API key echoed back in response.
x-hmac-signature
string
Response body signed with the shared secret key. Required to authenticate the response sender.
server_error

Unexpected error occurred while processing the request

{
  "status": "fail",
  "code": "1101",
  "message": "Something went wrong"
}
object
status
string
Valid values[ "fail" ]
Examplefail
code
string
Example1101
message
string
ExampleSomething went wrong



Document Versioning

Changelog

Date

Description

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