Skip to main content
GET
/
audit
/
{auditID}
Get Audit Record
curl --request GET \
  --url https://api.uip.digital/v1/audit/{auditID} \
  --header 'Authorization: Bearer <token>'
{
  "audit": {
    "created_at": "2025-01-11T14:30:00Z",
    "requester_uip_id": "business_abc123",
    "requester_sign_intent": "Sign Employment Contract",
    "requester_sign_information": "Please review and sign your employment contract by January 31, 2025.",
    "signatoree_uip_id": "user_def456",
    "message_ref": "msg_xyz789abc123",
    "attachment_refs": [
      "audit_abc123___msg_xyz789___contract.pdf"
    ],
    "audit_type": "message",
    "requester_name": "HR Manager",
    "signatoree_name": "John Doe",
    "requester_business_name": "Acme Corp",
    "signed_accepted": true
  },
  "attachments": [
    {
      "filename": "contract.pdf",
      "content_type": "application/pdf",
      "content": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC9UeXBlL0NhdGFs...",
      "size": 245678
    }
  ]
}
Retrieve the complete, permanent audit record for any completed action using the audit ID from webhook responses. Returns verified identity information, timestamps, action details, and any attached documents. Audit records are cryptographically secured, permanently stored, and can be queried at any time for legal verification, compliance, and dispute resolution.

Request

Headers

HeaderRequiredDescription
AuthorizationYesBearer token with your API key: Bearer YOUR_API_KEY

Path Parameters

auditID
string
required
The audit ID returned in webhook responses (the audit_id field).Example: "audit_9z8y7x6w5v4u"Where to get this: Webhook responses from Sign API, Message API (with signature), and Identify API all include an audit_id field. Save this ID to query the full audit record later.

Response

Success Response (200 OK)

Returns a JSON object containing the complete audit record and any attachments.
audit
object
required
Complete audit record with all action details
attachments
array
required
Array of PDF attachments that were included with the message. Empty array if no attachments.

Example Request

curl -X GET "https://api.uip.digital/v1/audit/audit_9z8y7x6w5v4u" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response (Signed Message with Attachment)

{
  "audit": {
    "created_at": "2025-01-11T14:30:00Z",
    "requester_uip_id": "business_abc123",
    "requester_sign_intent": "Sign Employment Contract",
    "requester_sign_information": "Please review and sign your employment contract by January 31, 2025.",
    "signatoree_uip_id": "user_def456",
    "message_ref": "msg_xyz789abc123",
    "attachment_refs": ["audit_abc123___msg_xyz789___contract.pdf"],
    "audit_type": "message",
    "requester_name": "HR Manager",
    "signatoree_name": "John Doe",
    "requester_business_name": "Acme Corp",
    "signed_accepted": true
  },
  "attachments": [
    {
      "filename": "contract.pdf",
      "content_type": "application/pdf",
      "content": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC9UeXBlL0NhdGFs...",
      "size": 245678
    }
  ]
}

Example Response (Declined Lightweight Signature)

{
  "audit": {
    "created_at": "2025-01-11T10:15:00Z",
    "requester_uip_id": "business_abc123",
    "requester_sign_intent": "Sign Terms of Service",
    "requester_sign_information": "I agree to the Terms of Service version 2.1",
    "signatoree_uip_id": "user_xyz789",
    "message_ref": null,
    "attachment_refs": null,
    "audit_type": "sign",
    "requester_name": "Platform Admin",
    "signatoree_name": "Jane Smith",
    "requester_business_name": "Tech Startup Inc",
    "signed_accepted": false
  },
  "attachments": []
}

Errors

See the Error Handling Guide for comprehensive error handling strategies. Possible error codes for this endpoint: Authentication Errors:
  • auth/missing-api-key - No API key provided in Authorization header
  • auth/revoked-api-key - API key has been revoked
  • auth/unauthorized - You do not own this audit record
Request Validation Errors:
  • request/invalid-path - Missing audit ID or audit ID parameter is empty
  • request/not-found - No such registered route in API service
Resource Errors:
  • resource/not-found - Audit record not found, API key not found, or attachment not found
Internal Errors:
  • internal/server-error - Failed to fetch audit record, decode audit data, or fetch attachments

Determining Signature Outcome

The signed_accepted field is the definitive indicator of whether a user signed or declined:
const auditResponse = await fetch(
  `https://api.uip.digital/v1/audit/${auditId}`,
  {
    headers: {
      'Authorization': `Bearer ${YOUR_API_KEY}`
    }
  }
);

const { audit, attachments } = await auditResponse.json();

if (audit.signed_accepted) {
  console.log(`${audit.signatoree_name} signed the document`);
  // Process signed document
  if (attachments.length > 0) {
    // Decode and save PDF attachments
    attachments.forEach(att => {
      const pdfBuffer = Buffer.from(att.content, 'base64');
      // Save or process PDF
    });
  }
} else {
  console.log(`${audit.signatoree_name} declined to sign`);
  // Handle declined signature
}

Implementation Flow

1

Request Signature or Authentication

Use Sign API, Message API (with signature), or Identify API to request an action from a user
2

Receive Webhook

When the user completes the action, your webhook receives the event with an audit_id field
3

Save Audit ID

Store the audit_id in your database for permanent reference and compliance tracking
4

Query Audit Record

Call the Audit API with the audit_id to retrieve complete action details
5

Check signed_accepted

Use the signed_accepted field to determine if the user signed/accepted or declined
6

Process Attachments

If attachments are present, decode the base64 content to retrieve the original PDFs
7

Store for Compliance

Save the complete audit record and attachments for legal verification and compliance requirements

Best Practices

Always Save Audit IDs

Store audit_id from every webhook response. This is your permanent proof of action and the only way to retrieve full audit details.

Check signed_accepted

Use the signed_accepted boolean field to determine outcome. Don’t rely on audit_type alone—it only tells you the API used, not the result.

Decode Attachments Properly

Use base64 decoding to convert attachment content back to PDF. Verify file integrity after decoding.

Store Complete Records

Save the entire audit response for compliance. Include audit record, attachments, and metadata in your database.

Common Use Cases

Generate compliance reports showing all signatures and authentications for regulatory audits.
// Query audit records for compliance report
const auditIds = await db.signatures.find({ month: '2025-01' });

const complianceReport = await Promise.all(
  auditIds.map(async ({ audit_id }) => {
    const response = await fetch(
      `https://api.uip.digital/v1/audit/${audit_id}`,
      { headers: { 'Authorization': `Bearer ${YOUR_API_KEY}` } }
    );
    const { audit } = await response.json();

    return {
      date: audit.created_at,
      action: audit.audit_type,
      signatory: audit.signatoree_name,
      intent: audit.requester_sign_intent,
      outcome: audit.signed_accepted ? 'Signed' : 'Declined'
    };
  })
);

// Generate compliance PDF or CSV
Resolve “who signed what when” disputes with cryptographically verified audit records.
// Customer claims they never signed
const dispute = {
  customer_name: "John Doe",
  claimed_audit_id: "audit_9z8y7x6w5v4u"
};

const response = await fetch(
  `https://api.uip.digital/v1/audit/${dispute.claimed_audit_id}`,
  { headers: { 'Authorization': `Bearer ${YOUR_API_KEY}` } }
);

const { audit } = await response.json();

// Verify claims against audit record
const verification = {
  signatory_name: audit.signatoree_name,
  signed_at: audit.created_at,
  signed: audit.signed_accepted,
  biometric_verified: true, // All UIP signatures require biometric verification
  government_verified_identity: true
};

// Present verification to customer or legal team
Retrieve signed PDFs from audit records for archiving or distribution.
// Employee requests copy of signed employment contract
const employeeRequest = {
  employee_id: "emp_12345",
  document_type: "employment_contract"
};

// Look up audit ID from your database
const { audit_id } = await db.documents.findOne({
  employee_id: employeeRequest.employee_id,
  document_type: employeeRequest.document_type
});

// Retrieve audit record with attachments
const response = await fetch(
  `https://api.uip.digital/v1/audit/${audit_id}`,
  { headers: { 'Authorization': `Bearer ${YOUR_API_KEY}` } }
);

const { audit, attachments } = await response.json();

// Decode and send PDF to employee
if (attachments.length > 0) {
  const pdfBuffer = Buffer.from(attachments[0].content, 'base64');
  // Email PDF to employee or provide download link
}

Authorizations

Authorization
string
header
required

Use your UIP API key as a bearer token

Path Parameters

auditID
string
required

The audit ID returned from webhook responses (audit_id field)

Response

200 - application/json

Audit record retrieved

audit
object
attachments
object[]

Array of PDF attachments. Empty array if no attachments.