List documents

You can retrieve all documents uploaded to a verification using the GET endpoint. This is useful for displaying document status to users or for auditing purposes.

GET/v5/verifications/:trace/documents

List all documents

This endpoint returns all documents associated with a verification. Each document includes metadata such as the document type, upload status, file name, and timestamps.

Path parameters

Name
trace
Type
string
Description
The unique identifier for the verification (received when creating the verification).

Response fields

The response contains a data.documents array. Each document includes:

Field	Type	Description
`id`	string	Unique document identifier.
`kind`	string	Document type (e.g., `trustDeed`, `partnershipAgreement`).
`stakeholderId`	string	Optional. Reference to stakeholder (for stakeholder-specific documents).
`storagePath`	string	Internal storage path for the document.
`name`	string	File name.
`description`	string	Human-readable description.
`reason`	string	Reason for uploading the document.
`status`	string	Document status: `current`, `error`, `deleted`, or `superseded`.
`mimeType`	string	MIME type of the document.
`timeline`	array	Optional. Array of events/actions related to the document.
`size`	number	File size in bytes.
`createdAt`	number	Unix timestamp of creation.
`updatedAt`	number	Unix timestamp of last update.
`createdTime`	string	Human-readable creation time.
`updatedTime`	string	Human-readable update time.

This endpoint returns document metadata only. To download a specific document, use the Get a specific document endpoint, which provides a signed download URL.

Request

GET

/v5/verifications/:trace/documents

curl https://dev.bronid.com/v5/verifications/abc123-verification-trace/documents \
  --user "XL7ULiU6B4QE9Y2iWFZnhtMDKFN2:api_sec_NJAtNcRtUrPlf7xYDrMNP9URI-ZfN314"

Response

{
  "timestamp": "2026-01-30T04:00:00.000Z",
  "serviceUid": "XL7ULiU6B4QE9Y2iWFZnhtMDKFN2",
  "trace": "abc123-verification-trace",
  "path": "/v5/verifications/:trace/documents",
  "pathParams": {
    "trace": "abc123-verification-trace"
  },
  "statusCode": 200,
  "message": "Files listed successfully.",
  "help": null,
  "status": "success",
  "data": {
    "documents": [
      {
        "id": "doc-id-123",
        "kind": "trustDeed",
        "storagePath": "extracts/files/.../doc-id-123",
        "name": "trust-deed.pdf",
        "description": "Trust deed for My Company",
        "reason": "",
        "status": "current",
        "mimeType": "application/pdf",
        "timeline": [],
        "size": 245678,
        "createdAt": 1737254548899,
        "updatedAt": 1737254548899,
        "createdTime": "30/01/2026 14:00:00",
        "updatedTime": "30/01/2026 14:00:00"
      },
      {
        "id": "doc-id-456",
        "kind": "certificateOfIncorporation",
        "stakeholderId": "stk-id-123",
        "storagePath": "extracts/files/.../doc-id-456",
        "name": "certificate.pdf",
        "description": "Certificate of incorporation",
        "reason": "",
        "status": "current",
        "mimeType": "application/pdf",
        "timeline": [],
        "size": 125000,
        "createdAt": 1737254600000,
        "updatedAt": 1737254600000,
        "createdTime": "30/01/2026 14:05:00",
        "updatedTime": "30/01/2026 14:05:00"
      }
    ]
  },
  "error": null
}

GET/v5/verifications/:trace/documents/:documentId

Get a specific document

To retrieve details about a specific document, including a signed download URL, use the document ID in the path.

Path parameters

Name
trace
Type
string
Description
The unique identifier for the verification.
Name
documentId
Type
string
Description
The unique identifier for the document (from the list response).

Download URL

The response includes a download object with:

downloadUrl - A signed URL to download the document
expiresAt - Unix timestamp when the URL expires

Download URLs are valid for 15 minutes. After expiration, make another GET request to obtain a fresh URL.

Error responses

Status Code	Error Type	Description
404	`not_found`	Document not found for the given verification.

Request

GET

/v5/verifications/:trace/documents/:documentId

curl https://dev.bronid.com/v5/verifications/abc123-verification-trace/documents/doc-id-123 \
  --user "XL7ULiU6B4QE9Y2iWFZnhtMDKFN2:api_sec_NJAtNcRtUrPlf7xYDrMNP9URI-ZfN314"

Response

{
  "timestamp": "2026-01-30T04:05:00.000Z",
  "serviceUid": "XL7ULiU6B4QE9Y2iWFZnhtMDKFN2",
  "trace": "abc123-verification-trace",
  "path": "/v5/verifications/:trace/documents/:documentId",
  "pathParams": {
    "trace": "abc123-verification-trace",
    "documentId": "doc-id-123"
  },
  "statusCode": 200,
  "message": "Document details retrieved successfully.",
  "help": null,
  "status": "success",
  "data": {
    "id": "doc-id-123",
    "kind": "trustDeed",
    "storagePath": "extracts/files/.../doc-id-123",
    "name": "trust-deed.pdf",
    "description": "Trust deed for My Company",
    "reason": "Uploaded as requested",
    "status": "current",
    "mimeType": "application/pdf",
    "timeline": ["Document uploaded via API at 2026-01-30T04:00:00.000Z"],
    "size": 245678,
    "createdAt": 1737254548899,
    "updatedAt": 1737254548899,
    "createdTime": "30/01/2026 14:00:00",
    "updatedTime": "30/01/2026 14:00:00",
    "download": {
      "downloadUrl": "https://storage.googleapis.com/...",
      "expiresAt": 1737255448899
    }
  },
  "error": null
}

What's next?

Now that you know how to list and retrieve documents, explore the full Documents API reference for uploading documents and handling document types.