Certified Prints API

The Certified Prints API allows you to generate and retrieve certified document prints.

Overview

Certified Prints are official printed versions of documents with certification marks, timestamps, and audit information. These are used for compliance and legal purposes.

Key concepts: A Certified Print is a PDF with certification and audit information. The Certificate Number is a unique identifier in format CP-{date}-{hex} (for example, CP-20240115-A7B3C9D1). One-Time Download means each certified print can only be downloaded once. Access Key Isolation means access keys can only see prints they created.

Certified print lifecycle

Pending → Processing: Generation begins automatically after request.
Processing → Completed: PDF generation succeeds.
Processing → Failed: PDF generation encounters an error.
Completed → Downloaded: PDF is downloaded (one-time only).

Required scopes

Scope	Description
`certified-prints:read`	View and download certified prints
`certified-prints:write`	Generate new certified prints
`certified-prints`	Full access (read + write)

List Certified Prints

Retrieve certified prints for a package.

GET /api/packages/{vaultPackageId}/certified-prints

Required scope: certified-prints:read. Path parameter vaultPackageId (guid, required).

Response (200 OK)

[
  {
    "id": "8fa85f64-5717-4562-b3fc-2c963f66afa6",
    "certificateNumber": "CP-20240115-A7B3C9D1",
    "status": "Completed",
    "fileSizeBytes": 524288,
    "errorMessage": null,
    "createdAt": "2024-01-15T10:30:00Z",
    "downloadedAt": null,
    "canDownload": true
  }
]

Note: When using an Access Key, only prints created by that Access Key are returned.

Error responses: 404 — Package not found.

Get Certified Print

Retrieve details for a specific certified print.

GET /api/packages/{vaultPackageId}/certified-prints/{certifiedPrintId}

Required scope: certified-prints:read. Path parameters vaultPackageId and certifiedPrintId (both guid, required).

Response (200 OK): Returns a CertifiedPrintViewModel object.

Error responses: 403 — Access key did not create this print; 404 — Package or certified print not found.

Generate Certified Print

Request generation of a new certified print for a package.

POST /api/packages/{vaultPackageId}/certified-prints

Required scope: certified-prints:write. Path parameter vaultPackageId (guid, required).

Request body (optional)

Field	Type	Required	Description
`deliveryEmail`	string	No	Email for delivery notification
`deliveryAddress`	string	No	Physical delivery address
`deliveryPhone`	string	No	Phone number for contact

Response (202 Accepted)

{
  "id": "8fa85f64-5717-4562-b3fc-2c963f66afa6",
  "certificateNumber": "CP-20240115-A7B3C9D1",
  "status": "Pending",
  "fileSizeBytes": 0,
  "errorMessage": null,
  "createdAt": "2024-01-15T10:30:00Z",
  "downloadedAt": null,
  "canDownload": false
}

Note: The PDF is generated asynchronously. Poll the certified print or wait for the status to become “Completed” before downloading.

Error responses: 404 — Package not found.

Download Certified Print

Download the certified print PDF.

GET /api/packages/{vaultPackageId}/certified-prints/{certifiedPrintId}/download

Required scope: certified-prints:read. Path parameters vaultPackageId and certifiedPrintId (both guid, required).

Response: Returns the PDF file with Content-Type: application/pdf and Content-Disposition headers. Each certified print can only be downloaded once. After download, the downloadedAt timestamp is set and canDownload becomes false. Subsequent download attempts will fail.

Error responses: 400 — Print status is not “Completed”; 400 — Print has already been downloaded; 403 — Access key did not create this print; 404 — Package or certified print not found; 500 — PDF file not found in storage.

Response models (Certified Prints API)

CertifiedPrintViewModel

Field	Type	Description
`id`	guid	Unique identifier
`certificateNumber`	string	Certificate number (`CP-{date}-{hex}`)
`status`	string	`Pending`, `Processing`, `Completed`, or `Failed`
`fileSizeBytes`	integer	PDF file size (0 until completed)
`errorMessage`	string	Error details if status is Failed
`createdAt`	datetime	Request timestamp (ISO 8601)
`downloadedAt`	datetime	Download timestamp (null if not downloaded)
`canDownload`	boolean	True if Completed and not yet downloaded

Certified print status

Status	Description
`Pending`	Request received, queued for generation
`Processing`	PDF is being generated
`Completed`	PDF ready for download
`Failed`	Generation failed (see `errorMessage`)

Important notes

One-time download enforcement

Certified prints are designed for compliance purposes and can only be downloaded once. This ensures audit trail accuracy for when documents were retrieved, prevention of unauthorized distribution, and clear chain of custody documentation. If you need multiple copies, you must generate separate certified prints.

Access Key isolation

When using Access Keys, each key can only see and download certified prints that it created. This provides integration isolation (different systems see only their prints), security boundaries between API consumers, and clear accountability for print requests.

Asynchronous generation

PDF generation happens in the background because complex documents may take time to render, watermarks and certification marks are applied, and the API remains responsive during generation. Poll the certified print status or implement webhook handling to know when generation completes.

Next: Vault Fields API.