Audit API

Retrieve comprehensive audit trails for UIP signatures using task hashes. Provides legally admissible records of what was signed, when, by whom, and who requested the signature.

Overview

The Audit API provides immutable, cryptographically verifiable records of all UIP signatures. Use signature task hashes to retrieve complete audit trails that meet legal requirements for digital signature verification.

📋 What You Get

  • • Complete document content and metadata
  • • Exact timestamp of signature
  • • Verified signer identity information
  • • Requesting party details
  • • Cryptographic signature proof
  • • Document integrity verification

⚖️ Legal Compliance

  • ✓ eIDAS compliant audit trails
  • ✓ US ESIGN Act compliance
  • ✓ Tamper-evident records
  • ✓ Independent verification possible
  • ✓ Long-term signature validity

How Task Hashes Work

Every UIP signature generates a unique task hash that serves as an immutable reference to the complete signing transaction. This hash can be used indefinitely to retrieve the full audit trail.

1. Document Signed

User signs document via Sign API or Messaging API

2. Task Hash Generated

Unique hash created and returned in webhook

3. Audit Available

Use hash to retrieve full audit trail anytime

Endpoint

GET https://audit.api.uip.id/v1/{task_hash}

Headers

Authorization: Bearer YOUR_API_KEY

Path Parameters

ParameterTypeDescription
task_hashstringThe unique task hash returned from Sign API or Messaging API signature completion

Request Example

GET https://audit.api.uip.id/v1/task_a1b2c3d4e5f6789012345678901234567890abcdef
Authorization: Bearer your_api_key_here

💡 Getting Task Hashes

Task hashes are provided in the webhook response when a signature is completed via the Sign API or Messaging API. Store these hashes in your database to enable future audit lookups.

Response Format

The audit response contains the complete signature transaction record with all relevant details for legal verification.

{
  "task_hash": "task_a1b2c3d4e5f6789012345678901234567890abcdef",
  "signature_type": "document", // or "simple"
  "document": "base64_encoded_document_data", // actual file if document was attached
  "title": "Employment Contract - Senior Developer Position",
  "intent": "Please review and sign this employment contract",
  "signed_at": "2024-01-15T10:45:23.123Z",
  "signature": "uip_sig_def456ghi789...",
  "signer_info": {
    "uip_id": "uip_user_1234567890",
    "full_name": "Alice Johnson"
  },
  "requesting_party": {
    "uip_id": "uip_user_5432109876",
    "full_name": "John Smith",
    "api_key_id": "ak_987654321",
    "requested_at": "2024-01-15T10:30:00Z"
  },
  "status": "signed"
}

Response Fields

• task_hash - Unique signature identifier

• document - Base64 encoded document

• title - Document title

• intent - Message from requester

• signed_at - When signed

• signature - Cryptographic signature

• status - signed/pending/declined

Legal Use Cases

⚖️ Legal Disputes

  • • Prove document was signed by specific individual
  • • Demonstrate document integrity since signing
  • • Show exact time and circumstances of signature
  • • Verify identity of all parties involved

📊 Regulatory Compliance

  • • Satisfy audit requirements
  • • Demonstrate due diligence
  • • Provide evidence for regulatory filings
  • • Support compliance reporting

📋 Internal Audits

  • • Track signature workflows
  • • Verify employee acknowledgments
  • • Audit contractor agreements
  • • Monitor compliance training completion

🔒 Security Investigations

  • • Investigate unauthorized signatures
  • • Verify signature authenticity
  • • Track document access patterns
  • • Forensic analysis of signing events

Complete Implementation

// JavaScript implementation
async function getSignatureAuditTrail(taskHash) {
  try {
    const response = await fetch('https://audit.api.uip.id/v1/' + taskHash, {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer ' + YOUR_API_KEY
      }
    });

    if (!response.ok) {
      if (response.status === 404) {
        throw new Error('Task hash not found');
      }
      throw new Error('HTTP error! status: ' + response.status);
    }

    const auditData = await response.json();
    
    return auditData;
  } catch (error) {
    console.error('Audit retrieval failed:', error);
    throw error;
  }
}

// Generate audit report
function generateAuditReport(auditData) {
  return {
    documentTitle: auditData.title,
    signerName: auditData.signer_info.full_name,
    signerUipId: auditData.signer_info.uip_id,
    signedAt: new Date(auditData.signed_at),
    requestedBy: auditData.requesting_party.full_name,
    requestedAt: new Date(auditData.requesting_party.requested_at),
    signatureHash: auditData.signature,
    status: auditData.status
  };
}

// Usage examples

// Get audit trail from webhook task hash
const taskHash = 'task_a1b2c3d4e5f6789012345678901234567890abcdef';
const auditTrail = await getSignatureAuditTrail(taskHash);

// Generate summary report
const report = generateAuditReport(auditTrail);
console.log('Signature Report:', report);


// Export for legal use
const legalRecord = {
  signedDocument: auditTrail.title,
  signedBy: auditTrail.signer_info.full_name + ' (UIP: ' + auditTrail.signer_info.uip_id + ')',
  signedOn: auditTrail.signed_at,
  requestedBy: auditTrail.requesting_party.full_name,
  status: auditTrail.status,
  auditHash: auditTrail.task_hash
};

Next Steps

Ready to implement signature auditing in your application?

Get API Keys Sign API Documentation