Start a verification session
Initiates a new hosted verification session and returns an Emblem redirect_url.
callback_url must be HTTPS. On successful verification, Emblem redirects
the user to callback_url with query parameters result_token, session_id,
and optional state only. Verification facts must be obtained via
POST /api/v1/verify/validate. Failed and expired sessions do not
produce result_token values; use webhooks for lifecycle visibility. A
user who cancels mid-flow keeps an active, recoverable session, so no
terminal webhook is sent until it completes or expires.
Authorization
bearerAuth Your secret API key (emb_sk_...) from the Emblem dashboard. Pass as "Bearer emb_sk_..." in the Authorization header.
In: header
Request Body
application/json
The integration ID configured in the Emblem dashboard.
uuidWhere the user should be returned after verification. Must be HTTPS in production.
uriOptional state value returned unchanged in the callback.
length <= 500Optional publisher user identifier for analytics.
length <= 255Optional language code for the verification UI. Supported values are en, de, es, fr, pt, it. Locale variants (e.g. pt-BR, de-DE, it-IT) are normalized to the base language. When provided, the redirect_url will include a lang query parameter.
length <= 10Optional public API key (emb_pk_...) for client-side SDK usage. Not the secret key — the secret key goes in the Authorization header.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://app.emblemapp.com/api/v1/verify/start" \ -H "Content-Type: application/json" \ -d '{ "integration_id": "", "callback_url": "https://yoursite.com/callback" }'{
"session_id": "string",
"redirect_url": "http://example.com",
"expires_at": "2019-08-24T14:15:22Z"
}{
"error": "string",
"error_code": "string",
"message": "string",
"code": "INVALID_REQUEST",
"details": [
"string"
],
"request_id": "string",
"correlation_id": "string"
}{
"error": "string",
"error_code": "string",
"message": "string",
"code": "INVALID_REQUEST",
"details": [
"string"
],
"request_id": "string",
"correlation_id": "string"
}{
"error": "string",
"error_code": "string",
"message": "string",
"code": "INVALID_REQUEST",
"details": [
"string"
],
"request_id": "string",
"correlation_id": "string"
}{
"error": "string",
"error_code": "string",
"message": "string",
"code": "INVALID_REQUEST",
"details": [
"string"
],
"request_id": "string",
"correlation_id": "string"
}{
"error": "string",
"error_code": "string",
"message": "string",
"code": "INVALID_REQUEST",
"details": [
"string"
],
"request_id": "string",
"correlation_id": "string"
}{
"error": "string",
"error_code": "string",
"message": "string",
"code": "INVALID_REQUEST",
"details": [
"string"
],
"request_id": "string",
"correlation_id": "string"
}{
"error": "string",
"error_code": "string",
"message": "string",
"code": "INVALID_REQUEST",
"details": [
"string"
],
"request_id": "string",
"correlation_id": "string"
}