Attestations API

Attestations provide cryptographic proof that an identity verification was completed. They are designed for e-signature integration, allowing you to embed verification evidence directly into signed documents.

Overview

What are Attestations?

An attestation is a signed, tamper-proof record that proves:

Who was verified (applicant identity)
When verification occurred (timestamp)
What checks passed (document, biometric, liveness, etc.)
Result of the verification (approved, rejected, review_required)

Use Cases

Use Case	Description
E-Signature Integration	Embed attestation IDs in signed PDFs to prove signer identity
Compliance Evidence	Provide auditable proof of KYC completion
Third-Party Verification	Allow external parties to validate verification claims
Document Notarization	Link verified identity to notarized documents

Attestation ID Format

Attestation IDs use the prefix att_ followed by 8 alphanumeric characters:

att_8f3a2b1c

This format is optimized for embedding in documents and QR codes.

Endpoints

Get or Create Attestation

Creates an attestation for a completed verification session, or returns an existing one if already created.

GET /api/v1/verifications/{session_id}/attestation

Authentication: API Key required (X-API-Key header)

Path Parameters

Parameter	Type	Description
`session_id`	UUID	The verification session ID

Response

{
  "attestation_id": "att_8f3a2b1c",
  "session_id": "ses_abc123",
  "applicant_id": "app_xyz789",
  "verified_at": "2026-01-31T20:45:00Z",
  "result": "approved",
  "checks_passed": ["id_document", "face_match", "liveness"],
  "checks_details": {
    "id_document": {
      "type": "passport",
      "country": "US",
      "confidence": 0.98
    },
    "face_match": {
      "similarity": 0.95
    },
    "liveness": {
      "is_live": true
    }
  },
  "signature": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "verify_url": "https://api.bytrustgate.com/api/v1/verify-attestation/att_8f3a2b1c",
  "is_valid": true,
  "revoked_at": null,
  "revocation_reason": null,
  "created_at": "2026-01-31T20:45:30Z"
}

Error Responses

Status	Code	Description
404	Not Found	Verification session not found
400	Bad Request	Session not completed (status must be `completed`)
401	Unauthorized	Invalid or missing API key

Example

curl -X GET "https://api.bytrustgate.com/api/v1/verifications/550e8400-e29b-41d4-a716-446655440000/attestation" \
  -H "X-API-Key: sk_live_xxx"

Get Attestation by ID

Retrieve an existing attestation by its ID.

GET /api/v1/attestations/{attestation_id}

Authentication: API Key required (X-API-Key header)

Path Parameters

Parameter	Type	Description
`attestation_id`	string	The attestation ID (e.g., `att_8f3a2b1c`)

Response

Same schema as Get or Create Attestation.

Example

curl -X GET "https://api.bytrustgate.com/api/v1/attestations/att_8f3a2b1c" \
  -H "X-API-Key: sk_live_xxx"

Public Verification

Publicly verify an attestation without authentication. This endpoint is designed for third-party verification of embedded attestations.

GET /api/v1/verify-attestation/{attestation_id}

Authentication: None required (public endpoint)

Rate Limit: 60 requests per minute

Path Parameters

Parameter	Type	Description
`attestation_id`	string	The attestation ID to verify

Response

{
  "attestation_id": "att_8f3a2b1c",
  "verified_at": "2026-01-31T20:45:00Z",
  "result": "approved",
  "checks_passed": ["id_document", "face_match", "liveness"],
  "is_valid": true,
  "revoked_at": null,
  "revocation_reason": null
}

Privacy Note: The public response intentionally excludes applicant_id and detailed check information to protect privacy.

Revoked Attestation Response

If an attestation has been revoked:

{
  "attestation_id": "att_8f3a2b1c",
  "verified_at": "2026-01-31T20:45:00Z",
  "result": "approved",
  "checks_passed": ["id_document", "face_match", "liveness"],
  "is_valid": false,
  "revoked_at": "2026-02-15T10:30:00Z",
  "revocation_reason": "Identity compromise detected"
}

Example

curl -X GET "https://api.bytrustgate.com/api/v1/verify-attestation/att_8f3a2b1c"

Revoke Attestation

Permanently revoke an attestation. Once revoked, the attestation will show as invalid when verified publicly.

POST /api/v1/attestations/{attestation_id}/revoke

Authentication: API Key required (X-API-Key header)

Path Parameters

Parameter	Type	Description
`attestation_id`	string	The attestation ID to revoke

Request Body

{
  "reason": "Identity compromise detected"
}

Field	Type	Required	Description
`reason`	string	Yes	Reason for revocation (1-255 characters)

Response

{
  "attestation_id": "att_8f3a2b1c",
  "revoked_at": "2026-02-15T10:30:00Z",
  "revocation_reason": "Identity compromise detected"
}

When to Revoke

Fraudulent verification - Original verification was fraudulent
Identity compromise - User's identity has been compromised
Created in error - Attestation was created by mistake
Compliance requirement - Regulatory or legal requirement to invalidate

Warning: Revocation is permanent and cannot be undone.

Example

curl -X POST "https://api.bytrustgate.com/api/v1/attestations/att_8f3a2b1c/revoke" \
  -H "X-API-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Identity compromise detected"
  }'

List Applicant Attestations

List all attestations for a specific applicant.

GET /api/v1/applicants/{applicant_id}/attestations

Authentication: API Key required (X-API-Key header)

Path Parameters

Parameter	Type	Description
`applicant_id`	UUID	The applicant ID

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	50	Maximum attestations to return (1-100)
`offset`	integer	0	Number of attestations to skip

Response

{
  "attestations": [
    {
      "attestation_id": "att_8f3a2b1c",
      "session_id": "ses_abc123",
      "applicant_id": "app_xyz789",
      "verified_at": "2026-01-31T20:45:00Z",
      "result": "approved",
      "checks_passed": ["id_document", "face_match", "liveness"],
      "checks_details": { ... },
      "signature": "eyJhbGciOiJIUzI1NiIs...",
      "verify_url": "https://api.bytrustgate.com/api/v1/verify-attestation/att_8f3a2b1c",
      "is_valid": true,
      "revoked_at": null,
      "revocation_reason": null,
      "created_at": "2026-01-31T20:45:30Z"
    }
  ],
  "total": 1
}

Example

curl -X GET "https://api.bytrustgate.com/api/v1/applicants/550e8400-e29b-41d4-a716-446655440000/attestations?limit=10" \
  -H "X-API-Key: sk_live_xxx"

Response Schemas

AttestationResponse

Full attestation response returned from authenticated endpoints.

Field	Type	Description
`attestation_id`	string	Unique attestation identifier (`att_xxxxxxxx`)
`session_id`	string	Session ID if created from session (nullable)
`applicant_id`	string	Applicant ID who was verified
`verified_at`	datetime	When verification was completed
`result`	string	Verification result: `approved`, `rejected`, `review_required`
`checks_passed`	string[]	List of checks that passed
`checks_details`	object	Detailed results for each check
`signature`	string	JWT signature for cryptographic verification
`verify_url`	string	Public URL to verify this attestation
`is_valid`	boolean	Whether attestation is still valid (not revoked)
`revoked_at`	datetime	When revoked, if applicable (nullable)
`revocation_reason`	string	Reason for revocation (nullable)
`created_at`	datetime	When attestation was created

AttestationVerifyResponse

Minimal response for public verification endpoint.

Field	Type	Description
`attestation_id`	string	Unique attestation identifier
`verified_at`	datetime	When verification was completed
`result`	string	Verification result
`checks_passed`	string[]	List of checks that passed
`is_valid`	boolean	False if attestation has been revoked
`revoked_at`	datetime	When revoked (nullable)
`revocation_reason`	string	Reason for revocation (nullable)

CheckDetails

Details about individual verification checks (within checks_details).

Field	Type	Description
`type`	string	Document type (e.g., "passport", "driver_license")
`country`	string	Issuing country code
`confidence`	float	Confidence score (0.0 - 1.0)
`similarity`	float	Face similarity score (0.0 - 1.0)
`is_live`	boolean	Liveness check result

PDF Embedding Guide

Embed attestation IDs in signed PDFs to provide cryptographic proof of identity verification.

Embedding Workflow

1. Complete verification ──> 2. Create attestation ──> 3. Embed in PDF ──> 4. Sign document
                                     │
                                     └──> att_8f3a2b1c

Embedding Methods

Add attestation reference to the document footer:

Identity verified by TrustGate
Attestation ID: att_8f3a2b1c
Verify at: https://api.bytrustgate.com/api/v1/verify-attestation/att_8f3a2b1c

Method 2: QR Code

Generate a QR code containing the verification URL:

const QRCode = require('qrcode');

const attestationId = 'att_8f3a2b1c';
const verifyUrl = `https://api.bytrustgate.com/api/v1/verify-attestation/${attestationId}`;

// Generate QR code image
const qrCodeImage = await QRCode.toDataURL(verifyUrl);

Method 3: PDF Metadata

Embed attestation data in PDF metadata fields:

// Using pdf-lib
const { PDFDocument } = require('pdf-lib');

const pdfDoc = await PDFDocument.load(existingPdfBytes);

pdfDoc.setAuthor('Verified by TrustGate');
pdfDoc.setKeywords(['trustgate', 'attestation', 'att_8f3a2b1c']);
pdfDoc.setCustomMetadata('trustgate_attestation_id', 'att_8f3a2b1c');
pdfDoc.setCustomMetadata('trustgate_verified_at', '2026-01-31T20:45:00Z');
pdfDoc.setCustomMetadata('trustgate_verify_url',
  'https://api.bytrustgate.com/api/v1/verify-attestation/att_8f3a2b1c');

const pdfBytes = await pdfDoc.save();

E-Signature Platform Integration

DocuSign

// Add custom fields to envelope
const envelope = {
  documents: [{ ... }],
  customFields: {
    textCustomFields: [
      {
        name: 'TrustGate Attestation ID',
        value: 'att_8f3a2b1c',
        show: true
      },
      {
        name: 'TrustGate Verification URL',
        value: 'https://api.bytrustgate.com/api/v1/verify-attestation/att_8f3a2b1c',
        show: true
      }
    ]
  }
};

Adobe Sign

Include attestation as a document field or in the audit trail.

Verification Flow

How third parties can validate attestations embedded in documents.

Verification Process

┌─────────────────────────────────────────────────────────────┐
│                    DOCUMENT RECIPIENT                        │
│                                                              │
│    1. Extract attestation ID from PDF                       │
│       (footer, QR code, or metadata)                        │
└─────────────────────────┬────────────────────────────────────┘
                          │
                          │ att_8f3a2b1c
                          v
┌─────────────────────────────────────────────────────────────┐
│                    TRUSTGATE API                             │
│                                                              │
│    GET /api/v1/verify-attestation/att_8f3a2b1c              │
│    (No authentication required)                              │
└─────────────────────────┬────────────────────────────────────┘
                          │
                          │ Response
                          v
┌─────────────────────────────────────────────────────────────┐
│                    VALIDATION RESULT                         │
│                                                              │
│    ✓ Attestation exists                                     │
│    ✓ Verification completed on 2026-01-31                    │
│    ✓ Result: approved                                        │
│    ✓ Checks passed: document, biometric, liveness           │
│    ✓ Not revoked (is_valid: true)                           │
└─────────────────────────────────────────────────────────────┘

JavaScript Verification Example

async function verifyAttestation(attestationId) {
  const response = await fetch(
    `https://api.bytrustgate.com/api/v1/verify-attestation/${attestationId}`
  );

  if (!response.ok) {
    if (response.status === 404) {
      return { valid: false, error: 'Attestation not found' };
    }
    throw new Error('Verification failed');
  }

  const data = await response.json();

  return {
    valid: data.is_valid,
    verifiedAt: data.verified_at,
    result: data.result,
    checksPassed: data.checks_passed,
    revoked: !data.is_valid,
    revokedAt: data.revoked_at,
    revocationReason: data.revocation_reason
  };
}

// Usage
const result = await verifyAttestation('att_8f3a2b1c');

if (result.valid) {
  console.log('Identity verification confirmed');
  console.log(`Verified on: ${result.verifiedAt}`);
  console.log(`Checks passed: ${result.checksPassed.join(', ')}`);
} else if (result.revoked) {
  console.warn('Attestation has been revoked');
  console.warn(`Reason: ${result.revocationReason}`);
} else {
  console.error('Invalid attestation');
}

Python Verification Example

import httpx

async def verify_attestation(attestation_id: str) -> dict:
    async with httpx.AsyncClient() as client:
        response = await client.get(
            f"https://api.bytrustgate.com/api/v1/verify-attestation/{attestation_id}"
        )

        if response.status_code == 404:
            return {"valid": False, "error": "Attestation not found"}

        response.raise_for_status()
        data = response.json()

        return {
            "valid": data["is_valid"],
            "verified_at": data["verified_at"],
            "result": data["result"],
            "checks_passed": data["checks_passed"],
            "revoked": not data["is_valid"],
            "revoked_at": data.get("revoked_at"),
            "revocation_reason": data.get("revocation_reason"),
        }

# Usage
result = await verify_attestation("att_8f3a2b1c")
if result["valid"]:
    print(f"Identity verified on {result['verified_at']}")

Best Practices

Security

Store attestation IDs - Keep a record of attestation IDs linked to your documents
Verify before trust - Always call the verification endpoint before relying on an attestation
Check revocation status - The is_valid field indicates if an attestation has been revoked
Use HTTPS - Always use secure connections when calling the API

Compliance

Audit trail - Attestations provide a complete audit trail for identity verification
Long-term retention - Attestations remain verifiable for the lifetime of your TrustGate account
Evidence export - Include attestation details in compliance evidence packages

Integration

Idempotent creation - Calling GET attestation multiple times for the same session returns the same attestation
Webhook notification - Subscribe to attestation.created events for real-time notifications
Bulk verification - For verifying multiple attestations, batch requests to stay within rate limits

Next Steps

Identity Verification - Set up verification workflows
Webhooks - Receive real-time attestation notifications
Compliance - Export verification evidence

Overview​

What are Attestations?​

Use Cases​

Attestation ID Format​

Endpoints​

Get or Create Attestation​

Path Parameters​

Response​

Error Responses​

Example​

Get Attestation by ID​

Path Parameters​

Response​

Example​

Public Verification​

Path Parameters​

Response​

Revoked Attestation Response​

Example​

Revoke Attestation​

Path Parameters​

Request Body​

Response​

When to Revoke​

Example​

List Applicant Attestations​

Path Parameters​

Query Parameters​

Response​

Example​

Response Schemas​

AttestationResponse​

AttestationVerifyResponse​

CheckDetails​

PDF Embedding Guide​

Embedding Workflow​

Embedding Methods​

Method 1: Document Footer​

Method 2: QR Code​

Method 3: PDF Metadata​

E-Signature Platform Integration​

DocuSign​

Adobe Sign​

Verification Flow​

Verification Process​

JavaScript Verification Example​

Python Verification Example​

Best Practices​

Security​

Compliance​

Integration​

Next Steps​

Overview

What are Attestations?

Use Cases

Attestation ID Format

Endpoints

Get or Create Attestation

Path Parameters

Response

Error Responses

Example

Get Attestation by ID

Path Parameters

Response

Example

Public Verification

Path Parameters

Response

Revoked Attestation Response

Example

Revoke Attestation

Path Parameters

Request Body

Response

When to Revoke

Example

List Applicant Attestations

Path Parameters

Query Parameters

Response

Example

Response Schemas

AttestationResponse

AttestationVerifyResponse

CheckDetails

PDF Embedding Guide

Embedding Workflow

Embedding Methods

Method 1: Document Footer

Method 2: QR Code

Method 3: PDF Metadata

E-Signature Platform Integration

DocuSign

Adobe Sign

Verification Flow

Verification Process

JavaScript Verification Example

Python Verification Example

Best Practices

Security

Compliance

Integration

Next Steps