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.

Create session

Updated
  • Updated on Jun 15, 2026
  • Published on Mar 8, 2026
Prev Next
Post
/v1/sessions

Creates a verification session with the data specified in the request body

When to use this endpoint

  • Use this endpoint to initiate a new verification session for an end-user. Every verification flow begins with creating a session.

Request body content

The contents of the request body depends on:

  • Whether you are using the SDK or API to capture end-user data
  • The type of verification solution the session is created for

Minimum request body:

  • Empty verification object

Payload examples:

  • Click on the "Show examples" button in "Request" section to see request body examples for specific solutions/products.

Response data

Once you create the verification session, you receive:

  • Unique session id (store this - required for other endpoints)
  • Unique sessionToken (legacy purposes, see FAQ)
  • Session URL in verification.url parameter (required for SDK integrations)

Getting session results

After the end-user completes the verification:

Implementation notes

  • Store the returned session id - it is required for all other session-related endpoints
  • Always ensure that you use the correct API URL to send requests. See the API URL section for more info.
  • See Javascript sample implementation for SDK integration examples
  • 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.

Additional info: end-user flow after session creation

  1. Create session → Get session.verification.url
  2. Redirect end-user to verification.url
  3. End-user completes verification flow
  4. End-user redirected to your callback URL (if configured)
  5. Receive webhook notification OR poll for results
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 under Settings > API keys.

Content-Type
stringRequired

Must be set to application/json

Valid values[ "application/json" ]
Exampleapplication/json
Body parameters

Session initialization data

minimal_payload

Empty verification object - minimum required to create a session

{
  "verification": {}
}
expanded_payload

Session with person data, document details, and end-user ID

{
  "verification": {
    "callback": "https://example.com/callback",
    "person": {
      "firstName": "John",
      "lastName": "Smith",
      "idNumber": "123456789"
    },
    "document": {
      "number": "B01234567",
      "type": "PASSPORT",
      "country": "US"
    },
    "endUserId": "c1de400b-1877-4284-8494-071d37916197"
  }
}
expanded_payload_with_hostAppLink

Session with person data, document details, end-user ID, and host app link

{
  "verification": {
    "callback": "https://example.com/callback",
    "hostAppLink": "myapp://verification/complete",
    "person": {
      "firstName": "John",
      "lastName": "Smith",
      "idNumber": "123456789"
    },
    "document": {
      "number": "B01234567",
      "type": "PASSPORT",
      "country": "US"
    },
    "endUserId": "c1de400b-1877-4284-8494-071d37916197"
  }
}
session_with_service_coverage

Session with service coverage configuration

{
  "verification": {
    "serviceCoverage": {
      "country": "US"
    }
  }
}
session_with_consent

Session with person data, document details, end-user ID, and consent array

{
  "verification": {
    "person": {
      "firstName": "John",
      "lastName": "Smith",
      "idNumber": "123456789"
    },
    "document": {
      "number": "B01234567",
      "type": "PASSPORT",
      "country": "US"
    },
    "endUserId": "c1de400b-1877-4284-8494-071d37916197",
    "consents": [
      {
        "type": "ine",
        "approved": true,
        "text": "User agrees to share their INE details",
        "timestamp": "2026-05-07T08:00:00Z"
      }
    ]
  }
}
aml_screening_standalone

Session for AML/sanctions screening with required person data

{
  "verification": {
    "person": {
      "firstName": "John",
      "lastName": "Smith",
      "dateOfBirth": "1990-01-01"
    }
  }
}
biometric_db_verification

Session for matching end-user's identity and biometric data against governmental biometric databases. Currently available only for Brazilian CPF Biometric Database.

{
  "verification": {
    "person": {
      "idNumber": 12345678901,
      "firstName": "João",
      "lastName": "Silva",
      "dateOfBirth": "1990-01-15"
    },
    "vendorData": 12345678,
    "endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4"
  }
}
br_cadastro_unico_database

Session to validate Brazilian users against social benefit registries. See here for full documentation.

{
  "verification": {
    "person": {
      "idNumber": 12345678901,
      "dateOfBirth": "1990-01-15"
    }
  }
}
br_probet_database

Session to validate users against Brazil's betting exclusion registries. See here for full documentation.

{
  "verification": {
    "person": {
      "idNumber": 12345678901,
      "dateOfBirth": "1990-01-15"
    }
  }
}
mx_curp_db_verification

Session for Mexican CURP database verification using person ID number

{
  "verification": {
    "person": {
      "idNumber": "VISH560427MSRLNL06"
    }
  }
}
mx_ine_db_verification_using_ife

Session for Mexican INE database verification using CIC and IFE identifier (OCR code) for card type D

{
  "verification": {
    "callback": "https://yourwebsite.com/webhook",
    "document": {
      "number": "123456789M00000000",
      "documentNumberIdentifiers": {
        "mxIfe": 1234567890123
      }
    }
  }
}
mx_ine_db_verification_using_ine

Session for Mexican INE database verification using CIC and INE identifier (Identificador Ciudadano) for card types E, F, G, and H

{
  "verification": {
    "callback": "https://yourwebsite.com/webhook",
    "document": {
      "number": "123456789M00000000",
      "documentNumberIdentifiers": {
        "mxIne": 1234567890123
      }
    }
  }
}
proof_of_address_address_matching

Proof of Address address matching session to compare addresses from two different sources

{
  "verification": {
    "person": {
      "firstName": "John",
      "lastName": "Smith"
    },
    "address": {
      "fullAddress": "123, Main Street, Your County, Anytown 12345"
    },
    "proofOfAddress": {
      "acceptableTypes": [
        {
          "name": "UTILITY_BILL"
        },
        {
          "name": "PHONE_BILL"
        },
        {
          "name": "TAX_DOCUMENT"
        }
      ]
    },
    "endUserId": "c1de400b-1877-4284-8494-071d37916197"
  }
}
proof_of_address_simple

Can be used for address extraction and address validation solutions. See the full Proof of Address documentation here

{
  "verification": {
    "proofOfAddress": {
      "acceptableTypes": [
        {
          "name": "UTILITY_BILL"
        },
        {
          "name": "PHONE_BILL"
        },
        {
          "name": "TAX_DOCUMENT"
        }
      ]
    },
    "endUserId": "c1de400b-1877-4284-8494-071d37916197"
  }
}
proof_of_address_with_name_match

Can be used for address extraction and address validation solutions. See the full Proof of Address documentation here

{
  "verification": {
    "person": {
      "firstName": "John",
      "lastName": "Smith"
    },
    "proofOfAddress": {
      "acceptableTypes": [
        {
          "name": "UTILITY_BILL"
        },
        {
          "name": "PHONE_BILL"
        },
        {
          "name": "TAX_DOCUMENT"
        }
      ]
    },
    "endUserId": "c1de400b-1877-4284-8494-071d37916197"
  }
}
selfie_to_selfie_biometric

Session for Biometric Authentication to verify identity by comparing two selfie images

{
  "verification": {
    "person": {
      "firstName": "John",
      "lastName": "Smith"
    },
    "endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4",
    "vendorData": 12345678
  }
}
session_with_tag_parameter

Session with custom tag parameter

{
  "verification": {
    "vendorData": 12345678,
    "tag": "your_custom_tag_max_64_characters"
  }
}
uk_diatf_m1b

Session for UK DIATF M1B verification with full address

{
  "verification": {
    "address": {
      "fullAddress": "123, Main Street, Your County, Anytown 12345"
    }
  }
}
us_light_kyc

Session for US Database Verification: Light KYC verification with person details and address

{
  "verification": {
    "person": {
      "firstName": "John",
      "lastName": "Smith",
      "dateOfBirth": "1990-01-01",
      "phoneNumber": "8888888888"
    },
    "address": {
      "fullAddress": "123, Main Street, Your County, Anytown 12345"
    }
  }
}
udocs_no_init_data

Session for Unstructured Docs verification without initData — for document extraction only (no InitData Matching validation).

{
  "verification": {}
}
udocs_with_init_data

Session for Unstructured Docs verification with all possible initData fields.

{
  "verification": {
    "document": {
      "number": "847293651024738569"
    },
    "person": {
      "fullName": "JUAN MARTINEZ",
      "occupation": "Driver"
    },
    "address": {
      "fullAddress": "AV INSURGENTES SUR 2847 PISO 3 COL DEL VALLE BENITO JUAREZ CIUDAD DE MEXICO MEXICO CP 03100"
    },
    "endUserId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}
us_ssn_validation

Session for US Database Verification: SSN check with document number and person data

{
  "verification": {
    "person": {
      "firstName": "John",
      "lastName": "Smith",
      "dateOfBirth": "1990-01-01"
    },
    "document": {
      "number": "123456789"
    }
  }
}
Expand All
object
verification
object Required

Verification object

callback
string

The callback URL to where the end-user is redirected after the verification session is completed.

Default is visible in the Veriff Customer Portal -> Settings. Changing the value in this request body will overwrite the default callback URL, but it will not change the callback URL that is visible in the Customer Portal.

Examplehttps://example.com/callback
person
object

Data about the person being verified.

firstName
string

Person's first name.

ExampleJohn
lastName
string

Person's last name.

ExampleSmith
idNumber
string

Person's national identification number.

Example123456789
phoneNumber
string

Person's phone number.

Example8888888888
gender
string

Person's gender.

Valid values[ "M", "MALE", "F", "FEMALE" ]
ExampleM
dateOfBirth
string (date)

Person's date of birth.

Format: YYYY-MM-DD.

Example1990-01-01
email
string

Person's email address.

Examplejohn.smith@example.com
maritalStatus
string

Person's marital status (mandatory only for some registry checks).

Valid values[ "single", "married", "divorced", "widowed" ]
Examplesingle
isDeceased
boolean

Person's deceased status (mandatory only for some registry checks).

Valid values[ true, false ]
Examplefalse
fullName
string

Person's full name.

Optional. Used as initData for Unstructured Docs InitData Matching validation or in Metadata Database Verification.

ExampleJUAN MARTINEZ
occupation
string

Person's occupation.

Optional. Used as initData for Unstructured Docs InitData Matching validation.

ExampleDriver
landLinePhoneNumber
string

Person's landline phone number.

Optional, used in some registry checks, for example Metadata Database Verification.

Example+1234567890
partnerFirstName
string

Person's partner's first name.

Optional, used in some registry checks, for example Metadata Database Verification.

ExampleEmily
partnerLastName
string

Person's partner's last name.

Optional, used in some registry checks, for example Metadata Database Verification.

ExampleJohnson
marriageDateOfEvent
string (date)

Person's marriage date. Format: YYYY-MM-DD.

Optional, used in some registry checks, for example Metadata Database Verification.

Example2015-06-30
middleName
string

Person's middle name.

Optional, used in some registry checks, for example Metadata Database Verification.

ExampleWilliam
secondLastName
string

Person's second last name (if applicable).

Optional, used in some registry checks, for example Metadata Database Verification.

ExampleGarcia
document
object

Data about the document of the person being verified.

number
string

Document number, [a-zA-Z0-9] characters only.

ExampleB01234567
country
string (ISO 3166-1 Alpha-2)

Document issuing country, in capital letters.

ExampleUS
type
string

Document type for Document + Selfie verification or Document-only verification

Valid values[ "ID_CARD", "PASSPORT", "DRIVERS_LICENSE", "RESIDENCE_PERMIT" ]
ExamplePASSPORT
firstIssue
string (date)

Date of the document's first issue. Format: YYYY-MM-DD.

Example2022-01-01
idCardType
string

Document type for the ID card, [a-zA-Z] characters only.

Optional, only required for Colombia identity verification.

Valid values[ "CE", "CC", "TI" ]
ExampleCC
documentNumberIdentifiers
object

Specific document number identifiers.

Optional, currently used only for the Official Database Verification step for INE database verification solution.

mxIne
string

Field representing the last 9 digits of the first line of the MRZ of an INE card. Also known as "Identificador del ciudadano".

Example158912347
mxIfe
string

Field representing the last 13 digits of the first line of the MRZ of an IFE card. Also known as "ocr".

Example1234567890123
validFrom
string (date)

Document issue date or valid-from date. Format: YYYY-MM-DD.

Optional, used in some registry checks, for example Metadata Database Verification.

Example2020-01-01
validUntil
string (date)

Document expiry date. Format: YYYY-MM-DD.

Optional, used in some registry checks, for example Metadata Database Verification.

Example2030-01-01
version
string

The version or revision number of the document.

Optional, used in some registry checks, for example Metadata Database Verification.

Example001
cardType
string

The specific type or category of the document.

Optional, used in some registry checks, for example Metadata Database Verification.

Valid values[ "SSS", "TIN", "GSIS" ]
ExampleTIN
cardNumber
string

The document's unique identification number.

Optional, used in some registry checks, for example Metadata Database Verification.

Example123456
stateOfIssue
string

The state or region where the document was issued.

Optional, used in some registry checks, for example Metadata Database Verification.

ExampleAL
referenceNumber
string

The reference number of the document.

Optional, used in some registry checks, for example Metadata Database Verification.

Example123456
registrationNumber
string

A registration identifier assigned to the document by the issuing authority.

Optional, used in some registry checks, for example Metadata Database Verification.

ExampleBOAB123456
address
object

Data about the address of the person being verified.

fullAddress
string

Full address.

Example123, Main Street, Your County, Anytown 12345
street
string

Street name.

Optional, used in some registry checks, for example Metadata Database Verification.

ExampleMain Street
houseNumber
string

House number.

Optional, used in some registry checks, for example Metadata Database Verification.

Example123
postcode
string

Postal code.

Optional, used in some registry checks, for example Metadata Database Verification.

Example12345
city
string

Any human settlement, including cities, towns, villages, hamlets, localities, etc.

Optional, used in some registry checks, for example Metadata Database Verification.

ExampleAnytown
state
string

Any administrative division, such as a state, province, or region.

Optional, used in some registry checks, for example Metadata Database Verification.

ExampleYour County
unit
string

Apartment, suite, or unit number.

Optional, used in some registry checks, for example Metadata Database Verification.

Example4B
neighbourhood
string

Usually an unofficial neighbourhood name like "Harlem", "South Bronx", or "Crown Heights".

Optional, used in some registry checks, for example Metadata Database Verification.

ExampleDowntown
proofOfAddress
object

Data about the PoA document of the person being verified.

Optional, should be only used in Proof of Address integrations.

acceptableTypes
Array of object (ProofOfAddressAcceptableTypes)

Accepted types for proof of address document.

This parameter should be sent only when using the proof of address solution and after the Acceptable document types feature has been configured for your integration.

object
name
string Required

Name of the accepted proof of address document type.

ExampleUTILITY_BILL
serviceCoverage
object | null

Object for specifying which country's verification services should be offered to the end-user.

country
string | null

ISO 3166-1 alpha-2 country code indicating which country's verification services should be offered to the end user. Not available by default.

Pattern^[A-Z]{2}$
ExampleUS
vendorData
string

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
endUserId
string (uuid)

The UUID that you created for your end-user, 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.

Examplec1de400b-1877-4284-8494-071d37916197
consents
Array of object (CreateSessionConsent)

Array of objects listing the type of consent given.

Optional, should be only included for solutions/products that require consent (e.g., MX INE Biometric Database or Metadata Database Verification).

object
type
string

Indicates the feature for which the consent is given.

Mandatory field for MX INE Biometric Database Verification and some registries in Metadata Database Verification.

Valid values[ "ine", "bipa", "aadhaar", "general", "dvs", "eid" ]
Exampleine
approved
boolean

If true, indicates that the consent has been given.

MX INE Biometric Database Verification requires that approved=true is sent. If false or missing, the session is not created.

A mandatory field for some registries in Metadata Database Verification.

Exampletrue
text
string

Consent text exactly (same language) as shown to the end-user.

Mandatory when type=eid and approved=true. Optional in all other cases.

ExampleUser agrees to share their INE details
timestamp
string (date-time)

Timestamp recording when the consent was given by the end-user, as combined ISO 8601 date and time in UTC. Always optional.

Format: YYYY-MM-DDTHH:MM:SS.sssZ.

Example2026-05-07T08:00:00Z
tag
string

Custom marker for the session that you create, max length 64 characters. Can be sent only if enabled for your integration.

Contact your Solutions Engineer or Veriff Customer Support for info and configuration.

Exampleyour_custom_tag_max_64_characters
hostAppLink
string | null

Optional link used to return the end-user to the host application during an external provider flow, which typically takes place in a browser. Send this field only if you have built your integration to return the end-user to the host app.

Pattern^[a-zA-Z][a-zA-Z0-9+.\-]*://
Examplemyapp://verification/complete
Responses
200

Created session

Headers
Content-Type
string
Response content type.
Exampleapplication/json
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.
Expand All
object
status
string

API request status.

Examplesuccess
verification
object

Verification object.

status
string

Verification session status.

Examplecreated
id
string (uuid)

UUID v4 which identifies the verification session.

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

URL of the verification session. The end-user is redirected here to go through the flow. It is a combination of the baseUrl and the sessionToken.

Examplehttps://exampleURL.com/v/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
sessionToken
string

Session-specific token of the verification.

ExampleeyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
host
string

The base url the sessionToken can be used for.

Examplehttps://exampleURL.com
endUserId
string (uuid) | null

The UUID that you created for your end-user, 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.

Examplec1de400b-1877-4284-8494-071d37916197
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
400

Bad request

Headers
Content-Type
string
Response content type.
Exampleapplication/json
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.
object
status
string
Valid values[ "fail" ]
Examplefail
code
string
Example1101
message
string
ExampleValidation failed
401

Unauthorized

Headers
Content-Type
string
Response content type.
Exampleapplication/json
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.
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.
429

Too many requests

Headers
Content-Type
string
Response content type.
Exampleapplication/json
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.
object
status
string
Valid values[ "fail" ]
Examplefail
code
string
Example1004
message
string
ExampleToo many requests.
500

Internal server error

Headers
Content-Type
string
Response content type.
Exampleapplication/json
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.
object
status
string
Valid values[ "fail" ]
Examplefail
code
string
Example1101
message
string
ExampleSomething went wrong

Payload compression support info

This endpoint accepts compressed request bodies with Content-Encoding: gzip or Content-Encoding: deflate. Note that this endpoint accepts a plain JSON payload, so compression is not always necessary. For typical session initialization payloads, the bandwidth savings are negligible and the extra CPU cost on the client side outweighs the benefit.

Where compression genuinely helps is when the request includes consent records that carry a text field. The consent text typically contains the full, human-readable consent statement that was shown to the end user, and can be several KB or larger (especially for legal or regulatory consents). In those cases, gzip or deflate can shrink the payload by 60–80%, which is worthwhile.

As a rule of thumb:

  • If your payload is just a verification block with no consents, or with consents that omit the text field, sending it uncompressed is fine.
  • If you include one or more consent objects with a non-trivial text field, prefer compression.

Request-body compression is a transport optimization, it does not change the signing contract. Your signature is always computed over the uncompressed JSON body. The server decompresses the payload before validating the signature.

No configuration changes are required for the integration to start using this feature. To use compression, include exactly one of these Content-Encoding values in your request:

  • gzip (recommended)
  • deflate

Combined values such as gzip, deflate or deflate, gzip are not supported. br is not supported on this endpoint.

Operation order

Getting the order right is critical. The signature must cover the uncompressed payload, and the compressed payload must decompress back to the exact bytes that were signed.

  1. Build the JSON payload
  2. Serialize the JSON to bytes
  3. Compute the signature over the serialized bytes ← sign BEFORE compressing
  4. Compress the serialized bytes (gzip or deflate)
  5. Send the compressed bytes with the matching Content-Encoding value

If you compress first and then sign the compressed bytes, signature validation will fail.

Request headers

  • x-auth-client = your API key
  • x-hmac-signature = Lowercase hex HMAC-SHA256 (64 chars, no prefix) of the uncompressed JSON body
  • Content-type = application/json
  • Content-Encoding = gzip (recommended) or deflate

Code examples

The examples below use gzip and include a consent with a long text field, which is the case where compression actually pays off. If you use deflate, keep the same signing flow and set Content-Encoding: deflate with deflate-compressed bytes.

Python

Text
import gzip
import hashlib
import hmac
import json
import requests
API_KEY = "your-api-key"
SHARED_SECRET = "your-shared-secret"
BASE_URL = "https://stationapi.veriff.com"
# A realistic consent text is typically much longer than this snippet.
CONSENT_TEXT = (
    "I consent to Veriff processing my personal data, including biometric data, "
    "for identity verification purposes in accordance with the Privacy Notice. "
    # ... full legal text continues, often several KB ...
)
# Step 1–2: Build and serialize the JSON payload
payload = {
    "verification": {
        "callback": "https://example.com/callback",
        "vendorData": "customer-123",
        "consents": [
            {
                "type": "general",
                "approved": True,
                "text": CONSENT_TEXT,
                "timestamp": "2026-05-08T10:00:00Z",
            }
        ],
    }
}
payload_bytes = json.dumps(payload, separators=(",", ":")).encode("utf-8")
# Step 3: Sign the UNCOMPRESSED payload
signature = hmac.new(
    SHARED_SECRET.encode("utf-8"),
    payload_bytes,
    hashlib.sha256,
).hexdigest()
# Step 4: Compress
compressed = gzip.compress(payload_bytes)
# Step 5: Send with Content-Encoding: gzip
response = requests.post(
    f"{BASE_URL}/v1/sessions",
    data=compressed,                        # raw bytes, not json=
    headers={
        "X-AUTH-CLIENT": API_KEY,
        "X-HMAC-SIGNATURE": signature,
        "Content-Type": "application/json",
        "Content-Encoding": "gzip",
    },
)
print(response.status_code, response.json())

Node.js

Text
const crypto = require('crypto');
const zlib = require('zlib');
const https = require('https');
const API_KEY = 'your-api-key';
const SHARED_SECRET = 'your-shared-secret';
const BASE_URL = 'stationapi.veriff.com';
// A realistic consent text is typically much longer than this snippet.
const CONSENT_TEXT =
  'I consent to Veriff processing my personal data, including biometric data, ' +
  'for identity verification purposes in accordance with the Privacy Notice. ' +
  // ... full legal text continues, often several KB ...
  '';
// Step 1–2: Build and serialize the JSON payload
const payload = {
  verification: {
    callback: 'https://example.com/callback',
    vendorData: 'customer-123',
    consents: [
      {
        type: 'general',
        approved: true,
        text: CONSENT_TEXT,
        timestamp: '2026-05-08T10:00:00Z',
      },
    ],
  },
};
const payloadBytes = Buffer.from(JSON.stringify(payload));
// Step 3: Sign the UNCOMPRESSED payload
const signature = crypto
  .createHmac('sha256', SHARED_SECRET)
  .update(payloadBytes)
  .digest('hex');
// Step 4: Compress
const compressed = zlib.gzipSync(payloadBytes);
// Step 5: Send with Content-Encoding: gzip
const req = https.request(
  {
    hostname: BASE_URL,
    path: '/v1/sessions',
    method: 'POST',
    headers: {
      'X-AUTH-CLIENT': API_KEY,
      'X-HMAC-SIGNATURE': signature,
      'Content-Type': 'application/json',
      'Content-Encoding': 'gzip',
      'Content-Length': compressed.length,
    },
  },
  (res) => {
    let body = '';
    res.on('data', (chunk) => (body += chunk));
    res.on('end', () => console.log(res.statusCode, body));
  }
);
req.write(compressed);
req.end();

Common mistakes

Compressing payloads that don't need it. For small session-creation payloads without a long consent text, the compression overhead is rarely worth it. Reach for compression when consent text or other large string fields push the body well beyond a few KB.

Signing the compressed bytes. The most common integration error. If you compress first and then compute the HMAC over the compressed output, the server will reject the request with a 401. Always sign the uncompressed JSON body.

Encoding/header mismatch. If you send Content-Encoding: gzip or Content-Encoding: deflate but the body is not encoded accordingly, the request fails with a 400. If you are not compressing, omit the Content-Encoding header.

Using json= in your HTTP library with compressed bytes. When sending compressed data, pass compressed bytes as a raw body (data= in Python requests, content= in httpx), not as a JSON parameter. Setting json= causes the HTTP library to re-serialize the payload, which defeats compression and breaks the signature.

Double compression. Do not set Content-Encoding if your HTTP client or proxy is already compressing the request transparently. If in doubt, check the outbound request body and Content-Encoding header.

Using unsupported or combined encodings. Supported values are exactly gzip or deflate. Combined values (for example, gzip, deflate) and other encodings (for example, br) fail with a 415 http error.



Document Versioning

Changelog

Date

Description

June 15, 2026

hostAppLink parameter added to the request body

June 3, 2026

serviceCoverage parameter added to the request body

May 19, 2026

"Payload compression" info added

consent object updated:

  • text string added
  • timestamp string added

Apr 24, 2026

Headers capitalization harmonized

Apr 17, 2026

Typo fixes

Apr 13, 2026

New parameters added to support the Metadata Database Verification solution session generation: to person object: fullName, landLinePhoneNumber, partnerLastName, partnerFirstName, marriageDateOfEvent, middleName, secondLastName; to document object: validFrom, validUntil, version, cardType, cardNumber, stateOfIssue, referenceNumber, registrationNumber; to address object: street, houseNumber, postcode, city, state, unit, neighbourhood. Also, new consent types dvs and general to consent.type.

Mar 18, 2026

tag parameter info and payload example added

Mar 9, 2026

Documentation updated: parent categories rearranged, intro section expanded, request and response examples added

Jan 6, 2026

New parameter occupation added to person object

Nov 6, 2025

"Article Versoning" renamed to "Changelog"
Changelog updated

Oct 30, 2025

documentNumberIdentifiers object added

Sep 16, 2025

vrf-integration-id header removed

Aug 6, 2025

Response headers added

Jul 11, 2025

Improved the note in the intro section about session creation, and about finding request parameters from Product Guides

Apr 30, 2025

- New parameters added to request's verification.person object: email, maritalStatus and isDeceased for registry checks

- New header vrf-integration-id added to support the new Flexible API keys solution

Apr 22, 2025

proofOfAddress object added to support sending proof of address data over API. This parameter is solution-specific, it is not commonly needed.

Mar 12, 2025

Documentation published