> ## 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. # List session 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](#https://devdocs.veriff.com/docs/mexico-nom-151-certification) #### 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/{id}/certificates/{certificateId}/files/{fileId}](https://devdocs.veriff.com/apidocs/v1sessionsidcertificatescertificateidfilesfileid-1) 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](https://devdocs.veriff.com/docs/hmac-authentication-and-endpoint-security#public-api-v1) authentication - 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 ## OpenAPI ````json GET /v1/sessions/{id}/certificates { "openapi": "3.0.0", "info": { "title": "Veriff Public API", "version": "1.0.0" }, "servers": [ { "url": "https://example-base-url" } ], "tags": [ { "name": "Session management", "description": "Create and manage verification sessions" }, { "name": "Data submission", "description": "Upload media and submit verification data during the session" }, { "name": "Session results", "description": "Retrieve verification decisions and results" }, { "name": "Media management", "description": "Access and download verification media files and media file-related data" }, { "name": "Database verification", "description": "Validate identity against national registries and databases" }, { "name": "Certificate management", "description": "Retrieve long-term preservation certificates and their source documents for a verification session" } ], "paths": { "/v1/sessions/{id}/certificates": { "get": { "summary": "List session certificates", "description": "### Returns the long-term preservation certificates associated with a specific verification session\n\n#### When to use this endpoint\n\n- Use this endpoint to retrieve the cryptographic preservation certificates generated for a verification session\n- 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\n- Common use cases include:\n - Obtaining a certificate for archival or regulatory compliance purposes\n - Retrieving the source documents that a certificate attests to\n - Building an audit trail that demonstrates the integrity of verification records\n- This endpoint is currently available as part of the [Mexico - NOM-151 Certification solution](#https://devdocs.veriff.com/docs/mexico-nom-151-certification)\n\n#### Response data\n\n- Returns a list of certificate objects associated with the specific `sessionId`. Each object includes:\n - Unique identifier (`id`), certificate `kind` (for example `nom-151-certificate`) and `format` (for example `pkcs7`)\n - `value`: the certificate itself, as a Base64-encoded CMS/PKCS#7 signed timestamp token\n - `createdAt`: the time the certificate was generated\n - `metadata`: certificate authority metadata, including the certificate serial number, issue date, hash algorithm and hash\n - `sourceDocuments`: the documents that the certificate attests to, each with a download `url`\n\n- The `metadata` fields are populated from the certificate authority response. Any field that the authority does not return is set to null.\n\n#### Implementation notes\n\n- Use the `sourceDocuments[].url` value together with [GET /v1/sessions/{id}/certificates/{certificateId}/files/{fileId}](https://devdocs.veriff.com/apidocs/v1sessionsidcertificatescertificateidfilesfileid-1) to download the document a certificate attests to\n- An empty `certificates` array indicates that no certificate has been generated for the session yet\n- A maximum of 2 certificates is returned. Pagination is not available\n- This endpoint requires session-level [HMAC signature](https://devdocs.veriff.com/docs/hmac-authentication-and-endpoint-security#public-api-v1) authentication\n- 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\n- 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\n", "operationId": "retrieveSessionCertificates", "tags": [ "Certificate management" ], "parameters": [ { "name": "id", "in": "path", "required": "true", "description": "Verification session ID.", "schema": { "type": "string", "format": "uuid" }, "example": "d69a07cf-4434-4d36-be6c-d22af7dc01fb" }, { "name": "X-AUTH-CLIENT", "in": "header", "required": "true", "description": "Your integration's API key (occasionally referred to as the \"Token\", \"API public key\" or \"Publishable key\").\nRequired for all API requests.\n\nYou can find your API key in the Veriff Customer Portal > Settings > API keys.\n", "schema": { "type": "string" }, "example": "your-api-key" }, { "name": "X-HMAC-SIGNATURE", "in": "header", "required": "true", "description": "Session ID signed with the shared secret key. Required to authenticate the request sender.", "schema": { "type": "string" }, "example": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6" } ], "responses": { "200": { "description": "Session certificates retrieved successfully", "headers": { "Content-Type": { "description": "Response content type.", "schema": { "type": "string", "example": "application/json" } }, "X-AUTH-CLIENT": { "description": "API key echoed back in response.", "schema": { "type": "string", "example": "your-api-key" } }, "X-HMAC-SIGNATURE": { "description": "Response body signed with the shared secret key. Required to authenticate the response sender.", "schema": { "type": "string", "example": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionCertificatesResponse" }, "examples": { "nom_151_certificate": { "summary": "Session with a NOM-151 preservation certificate", "value": { "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" } ] } ] } }, "no_certificate": { "summary": "Session with no certificate generated yet", "value": { "status": "success", "certificates": [] } } } } } }, "401": { "description": "Unauthorized", "headers": { "Content-Type": { "description": "Response content type.", "schema": { "type": "string", "example": "application/json" } }, "X-AUTH-CLIENT": { "description": "API key echoed back in response.", "schema": { "type": "string", "example": "your-api-key" } }, "X-HMAC-SIGNATURE": { "description": "Response body signed with the shared secret key.", "schema": { "type": "string", "example": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" }, "example": { "status": "fail", "code": "1101", "message": "Mandatory X-AUTH-CLIENT header containing the API key is missing from the request." } } } }, "404": { "description": "Session not found", "headers": { "Content-Type": { "description": "Response content type.", "schema": { "type": "string", "example": "application/json" } }, "X-AUTH-CLIENT": { "description": "API key echoed back in response.", "schema": { "type": "string", "example": "your-api-key" } }, "X-HMAC-SIGNATURE": { "description": "Response body signed with the shared secret key.", "schema": { "type": "string", "example": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundErrorResponse" }, "example": { "status": "fail", "code": "1101", "message": "Resource not found" } } } }, "500": { "description": "Internal server error", "headers": { "Content-Type": { "description": "Response content type.", "schema": { "type": "string", "example": "application/json" } }, "X-AUTH-CLIENT": { "description": "API key echoed back in response.", "schema": { "type": "string", "example": "your-api-key" } }, "X-HMAC-SIGNATURE": { "description": "Response body signed with the shared secret key.", "schema": { "type": "string", "example": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" }, "example": { "status": "fail", "code": "1101", "message": "Something went wrong" } } } } }, "x-d360-narrative-responses": "

Changelog

Date

Description

Sep 4, 2026

Documentation created

" } } }, "components": { "schemas": { "SessionCertificatesResponse": { "type": "object", "description": "List of long-term preservation certificates generated for a verification session.", "properties": { "status": { "type": "string", "description": "API request status", "example": "success" }, "certificates": { "type": "array", "description": "Array of certificate objects generated for the session. Empty when no certificate has been generated yet.", "items": { "$ref": "#/components/schemas/CertificateRecord" } } }, "required": [ "status", "certificates" ] }, "UnauthorizedErrorResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail" ], "example": "fail" }, "code": { "type": "string", "example": "1101" }, "message": { "type": "string", "example": "Mandatory X-AUTH-CLIENT header containing the API key is missing from the request." } }, "required": [ "status", "code", "message" ] }, "NotFoundErrorResponse": { "type": "object", "required": [ "status", "code", "message" ], "properties": { "status": { "type": "string", "enum": [ "fail" ], "example": "fail" }, "code": { "type": "string", "example": "1101" }, "message": { "type": "string", "example": "Resource not found" } } }, "InternalServerErrorResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail" ], "example": "fail" }, "code": { "type": "string", "example": "1101" }, "message": { "type": "string", "example": "Something went wrong" } }, "required": [ "status", "code", "message" ] }, "CertificateRecord": { "type": "object", "description": "A single long-term preservation certificate and the source documents it attests to.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the certificate.", "example": "27d303bb-6a1f-4c2e-9b1d-2f3a4b5c6d7e" }, "kind": { "type": "string", "description": "The kind of certificate. Identifies the preservation standard the certificate was issued under.", "example": "nom-151-certificate" }, "format": { "type": "string", "description": "The encoding format of the certificate `value`.", "example": "pkcs7" }, "value": { "type": "string", "description": "The certificate itself, as a Base64-encoded CMS/PKCS#7 signed timestamp token.", "example": "MIIPwTADAgEAMIIPuAYJKoZIhvcNAQcCoIIPqTCCD6UCAQMxDzANBglghkgBZQMEAgEFADCCAc0..." }, "createdAt": { "type": "string", "format": "date-time", "description": "The time the certificate was generated. Expressed in UTC and ends with the letter Z.", "example": "2026-06-15T09:17:53Z" }, "metadata": { "description": "Certificate authority metadata describing the issued certificate.", "allOf": [ { "$ref": "#/components/schemas/CertificateMetadata" } ] }, "sourceDocuments": { "type": "array", "description": "The documents that the certificate attests to. Each document can be downloaded using its `url`.", "items": { "$ref": "#/components/schemas/SourceDocument" } } }, "required": [ "id", "kind", "format", "value", "createdAt", "metadata", "sourceDocuments" ] }, "CertificateMetadata": { "type": "object", "description": "Metadata returned by the certificate authority for an issued certificate. A field is set to null when the authority does not return it.", "properties": { "certificateNumber": { "type": "string", "nullable": "true", "description": "Serial number of the certificate, as assigned by the certificate authority. Set to null when not provided.", "example": "02377f31" }, "issueDate": { "type": "string", "format": "date-time", "nullable": "true", "description": "The moment the certificate authority certified the data. Expressed in UTC and ends with the letter Z. Set to null when not provided.", "example": "2026-06-15T09:17:53Z" }, "hashAlgorithm": { "type": "string", "nullable": "true", "description": "The hash algorithm used to compute the certified hash. Set to null when not provided.", "example": "sha256" }, "hash": { "type": "string", "nullable": "true", "description": "The hash of the certified data. Set to null when not provided.", "example": "eJ8olhK7cR5v2iKnbFuRKngydS1Si6KVevSycRN6/dg=" } }, "required": [ "certificateNumber", "issueDate", "hashAlgorithm", "hash" ] }, "SourceDocument": { "type": "object", "description": "A document that a certificate attests to.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the source document.", "example": "a6a27f7a-3c4d-4e5f-8a9b-0c1d2e3f4a5b" }, "url": { "type": "string", "description": "Relative URL used to download the source document file.", "example": "/v1/sessions/{id}/certificates/{certificateId}/files/{fileId}" } }, "required": [ "id", "url" ] } } } } ````