List session certificates

Published on Sep 4, 2026

Prev Next

Get

/v1/sessions/{id}/certificates

Returns the long-term preservation certificates associated with a specific verification session

When to use this endpoint

Use this endpoint to retrieve the cryptographic preservation certificates generated for a verification session
A certificate provides proof that the session data existed in its current form at the certified moment in time, and that it has not been altered since
Common use cases include:
- Obtaining a certificate for archival or regulatory compliance purposes
- Retrieving the source documents that a certificate attests to
- Building an audit trail that demonstrates the integrity of verification records
This endpoint is currently available as part of the Mexico - NOM-151 Certification solution

Response data

Returns a list of certificate objects associated with the specific sessionId. Each object includes:
- Unique identifier (id), certificate kind (for example nom-151-certificate) and format (for example pkcs7)
- value: the certificate itself, as a Base64-encoded CMS/PKCS#7 signed timestamp token
- createdAt: the time the certificate was generated
- metadata: certificate authority metadata, including the certificate serial number, issue date, hash algorithm and hash
- sourceDocuments: the documents that the certificate attests to, each with a download url
The metadata fields are populated from the certificate authority response. Any field that the authority does not return is set to null.

Implementation notes

Use the sourceDocuments[].url value together with GET /v1/sessions//certificates//files/ to download the document a certificate attests to
An empty certificates array indicates that no certificate has been generated for the session yet
A maximum of 2 certificates is returned. Pagination is not available
This endpoint requires session-level HMAC signature authentication
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

Session ID signed with the shared secret key. Required to authenticate the request sender.

Examplea1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6

Path parameters

string (uuid) Required

Verification session ID.

Exampled69a07cf-4434-4d36-be6c-d22af7dc01fb

Responses

200

Session certificates retrieved successfully

Headers

Content-Type

string

Response content type.

Exampleapplication/json

X-AUTH-CLIENT

string

API key echoed back in response.

Exampleyour-api-key

X-HMAC-SIGNATURE

string

Response body signed with the shared secret key. Required to authenticate the response sender.

Examplea1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6

nom_151_certificate

Session with a NOM-151 preservation certificate

{
  "status": "success",
  "certificates": [
    {
      "id": "27d303bb-6a1f-4c2e-9b1d-2f3a4b5c6d7e",
      "kind": "nom-151-certificate",
      "format": "pkcs7",
      "value": "MIIPwTADAgEAMIIPuAYJKoZIhvcNAQcCoIIPqTCCD6UCAQMxDzANBglghkgBZQMEAgEFADCCAc0...",
      "createdAt": "2026-06-15T09:17:53Z",
      "metadata": {
        "certificateNumber": "02377f31",
        "issueDate": "2026-06-15T09:17:53Z",
        "hashAlgorithm": "sha256",
        "hash": "eJ8olhK7cR5v2iKnbFuRKngydS1Si6KVevSycRN6/dg="
      },
      "sourceDocuments": [
        {
          "id": "a6a27f7a-3c4d-4e5f-8a9b-0c1d2e3f4a5b",
          "url": "/v1/sessions/d69a07cf-4434-4d36-be6c-d22af7dc01fb/certificates/27d303bb-6a1f-4c2e-9b1d-2f3a4b5c6d7e/files/a6a27f7a-3c4d-4e5f-8a9b-0c1d2e3f4a5b"
        }
      ]
    }
  ]
}

Expand All

object

List of long-term preservation certificates generated for a verification session.

status

string

API request status

Examplesuccess

certificates

Array of object (CertificateRecord)

Array of certificate objects generated for the session. Empty when no certificate has been generated yet.

object

A single long-term preservation certificate and the source documents it attests to.

string (uuid)

Unique identifier of the certificate.

Example27d303bb-6a1f-4c2e-9b1d-2f3a4b5c6d7e

kind

string

The kind of certificate. Identifies the preservation standard the certificate was issued under.

Examplenom-151-certificate

format

string

The encoding format of the certificate value.

Examplepkcs7

value

string

The certificate itself, as a Base64-encoded CMS/PKCS#7 signed timestamp token.

ExampleMIIPwTADAgEAMIIPuAYJKoZIhvcNAQcCoIIPqTCCD6UCAQMxDzANBglghkgBZQMEAgEFADCCAc0...

createdAt

string (date-time)

The time the certificate was generated. Expressed in UTC and ends with the letter Z.

Example2026-06-15T09:17:53Z

metadata

object

Certificate authority metadata describing the issued certificate.

certificateNumber

string | null

Serial number of the certificate, as assigned by the certificate authority. Set to null when not provided.

Example02377f31

issueDate

string (date-time) | null

The moment the certificate authority certified the data. Expressed in UTC and ends with the letter Z. Set to null when not provided.

Example2026-06-15T09:17:53Z

hashAlgorithm

string | null

The hash algorithm used to compute the certified hash. Set to null when not provided.

Examplesha256

hash

string | null

The hash of the certified data. Set to null when not provided.

ExampleeJ8olhK7cR5v2iKnbFuRKngydS1Si6KVevSycRN6/dg=

sourceDocuments

Array of object (SourceDocument)

The documents that the certificate attests to. Each document can be downloaded using its url.

object

A document that a certificate attests to.

string (uuid)

Unique identifier of the source document.

Examplea6a27f7a-3c4d-4e5f-8a9b-0c1d2e3f4a5b

url

string

Relative URL used to download the source document file.

Example/v1/sessions/{id}/certificates/{certificateId}/files/{fileId}

401

Unauthorized

Headers

Content-Type

string

Response content type.

Exampleapplication/json

X-AUTH-CLIENT

string

API key echoed back in response.

Exampleyour-api-key

X-HMAC-SIGNATURE

string

Response body signed with the shared secret key.

Examplea1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6

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

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.

Exampleapplication/json

X-AUTH-CLIENT

string

API key echoed back in response.

Exampleyour-api-key

X-HMAC-SIGNATURE

string

Response body signed with the shared secret key.

Examplea1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6

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

Exampleapplication/json

X-AUTH-CLIENT

string

API key echoed back in response.

Exampleyour-api-key

X-HMAC-SIGNATURE

string

Response body signed with the shared secret key.

Examplea1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6

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

object

status

string

Valid values[ "fail" ]

Examplefail

code

string

Example1101

message

string

ExampleSomething went wrong

Changelog

Date	Description
Sep 4, 2026	Documentation created

Was this article helpful?