Documents

Documents allow you to upload and retrieve files for verifications using the V5 API.

Overview

Documents can be uploaded and retrieved at any point during the verification lifecycle. The documents API includes four endpoints:

POST /v5/verifications/{trace}/documents - Add a new document to the verification
PUT /v5/verifications/{trace}/documents/{documentId} - Respond to an info status request to upload a specific document
GET /v5/verifications/{trace}/documents - List document metadata for a verification
GET /v5/verifications/{trace}/documents/{documentId} - Retrieve a specific document and download URL

When to use each endpoint

POST (Add new document)

Use the POST endpoint when you want to add a new document to a verification. The system will generate a unique documentId for the uploaded document. This can be used at any stage of the verification lifecycle.

PUT (Upload requested document)

Use the PUT endpoint when responding to an info status request. When a verification transitions to info status, the remainingActions.document object contains specific documents that need to be uploaded, each with a pre-assigned documentId. Use the PUT endpoint with this documentId to fulfill the request, which automatically removes the document from the remainingActions list.

GET (List documents)

Use the GET list endpoint when you need all document records for a verification, for example to display upload status, audit submitted files, or locate a specific documentId.

GET (Get document)

Use the GET by ID endpoint when you need full metadata and a short-lived signed downloadUrl for a specific document.

All document endpoints require a valid trace identifier, which uniquely identifies the verification.

POST/v5/verifications/:trace/documents

Add new document

Upload a new document to an existing verification. The system generates a unique document ID. The request body must include a source field that determines the upload method.

Upload methods

URL: Use when the document is hosted at a publicly accessible URL. The server will fetch the document from the provided URL.
Base64: Use when you have the document content as a base64-encoded string.
Preupload: Use when you want to upload a document for a verification that is yet to be submitted, e.g. while the user is filling out the form.

Required attributes

Name
source
Type
string
Description
Upload method: url, base64, or preupload.
Name
data
Type
string
Description
The URL, base64-encoded content, or preupload reference ID.
Name
kind
Type
string
Description
Document type (e.g., trustDeed, passport). See Document Types below.
Name
mimeType
Type
string
Description
MIME type of the document (e.g., application/pdf, image/jpeg).

Optional attributes

Name
fileName
Type
string
Description
Original filename of the document.
Name
description
Type
string
Description
Human-readable description of the document.
Name
reason
Type
string
Description
Reason for uploading this document.
Name
stakeholderId
Type
string
Description
Reference to a stakeholder ID (for stakeholder-specific documents like IDs).

Request

POST

/v5/verifications/:trace/documents

curl -X POST "https://api.bronid.com/v5/verifications/{trace}/documents" \
  -H "Authorization: Basic {credentials}" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "url",
    "data": "https://example.com/documents/trust-deed.pdf",
    "kind": "trustDeed",
    "mimeType": "application/pdf",
    "fileName": "trust-deed.pdf",
    "description": "Trust deed document"
  }'

Response

{
  "serviceUid": "5qA5Hq0n1JQTY2TASItxYXSRyND3",
  "trace": "DriJoJAkKk-YUBKFVXW7c",
  "path": "/v5/verifications/:trace/documents",
  "pathParams": {
    "trace": "DriJoJAkKk-YUBKFVXW7c"
  },
  "timestamp": "2026-01-19T02:32:28.899Z",
  "status": "success",
  "statusCode": 200,
  "data": {
    "documentId": "z_dBQc-tkL7Ext04ifOhw"
  },
  "message": "File uploaded successfully.",
  "help": null,
  "error": null
}

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

Upload requested document

Upload a document to fulfill a specific document request from an info status verification. Use the documentId provided in the remainingActions.document object.

Path parameters

Name
trace
Type
string
Description
The unique identifier for the verification.
Name
documentId
Type
string
Description
The document ID from remainingActions.document.

When to use

When a verification has verificationStatus: "info", fetch the verification details to see the remainingActions. Use the id from each document entry as the documentId path parameter.

The request body is the same as the POST endpoint. See Add new document above.

Upon successful upload, the document is automatically removed from remainingActions.document. When all remaining actions are completed, the verification status transitions from info to pending.

Request

PUT

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

curl -X PUT "https://api.bronid.com/v5/verifications/{trace}/documents/{documentId}" \
  -H "Authorization: Basic {credentials}" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "url",
    "data": "https://example.com/documents/trust-deed.pdf",
    "kind": "trustDeed",
    "mimeType": "application/pdf",
    "fileName": "trust-deed.pdf"
  }'

remainingActions example

{
  "verificationStatus": "info",
  "remainingActions": {
    "document": {
      "doc-id-123": {
        "id": "doc-id-123",
        "type": "document",
        "name": "Trust Deed",
        "description": "The trust deed document for the entity",
        "reason": "Required to verify trust structure"
      }
    }
  }
}

GET/v5/verifications/:trace/documents

List documents

Retrieve a list of all documents uploaded to a verification. This is useful for displaying document status to users or for auditing purposes.

Path parameters

Name
trace
Type
string
Description
The unique identifier for 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 (for example, `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 document endpoint which provides a signed download URL.

Request

GET

/v5/verifications/:trace/documents

curl -X GET "https://api.bronid.com/v5/verifications/{trace}/documents" \
  -H "Authorization: Basic {credentials}"

Response

{
  "timestamp": "2026-01-19T02:35:00.000Z",
  "serviceUid": "5qA5Hq0n1JQTY2TASItxYXSRyND3",
  "trace": "DriJoJAkKk-YUBKFVXW7c",
  "path": "/v5/verifications/:trace/documents",
  "pathParams": {
    "trace": "DriJoJAkKk-YUBKFVXW7c"
  },
  "statusCode": 200,
  "message": "Files listed successfully.",
  "help": null,
  "status": "success",
  "data": {
    "documents": [
      {
        "id": "z_dBQc-tkL7Ext04ifOhw",
        "kind": "trustDeed",
        "storagePath": "extracts/files/.../z_dBQc-tkL7Ext04ifOhw",
        "name": "trust-deed.pdf",
        "description": "Trust deed for My Company",
        "reason": "",
        "status": "current",
        "mimeType": "application/pdf",
        "timeline": [],
        "size": 245678,
        "createdAt": 1737254548899,
        "updatedAt": 1737254548899,
        "createdTime": "19/01/2026 02:32:28",
        "updatedTime": "19/01/2026 02:32:28"
      },
      {
        "id": "abc123-document-id",
        "kind": "certificateOfIncorporation",
        "storagePath": "extracts/files/.../abc123-document-id",
        "name": "certificate.pdf",
        "description": "Certificate of incorporation",
        "reason": "",
        "status": "current",
        "mimeType": "application/pdf",
        "timeline": [],
        "size": 125000,
        "createdAt": 1737254600000,
        "updatedAt": 1737254600000,
        "createdTime": "19/01/2026 02:33:20",
        "updatedTime": "19/01/2026 02:33:20"
      }
    ]
  },
  "error": null
}

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

Get 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.

Download URL

The response includes a download object with:

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

Error responses

Status Code	Error Type	Description
404	`not_found`	`Document not found: {documentId}`

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

Request

GET

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

curl -X GET "https://api.bronid.com/v5/verifications/{trace}/documents/{documentId}" \
  -H "Authorization: Basic {credentials}"

Response

{
  "serviceUid": "5qA5Hq0n1JQTY2TASItxYXSRyND3",
  "trace": "DriJoJAkKk-YUBKFVXW7c",
  "path": "/v5/verifications/:trace/documents/:documentId",
  "pathParams": {
    "trace": "DriJoJAkKk-YUBKFVXW7c",
    "documentId": "z_dBQc-tkL7Ext04ifOhw"
  },
  "timestamp": "2026-01-19T02:35:00.000Z",
  "status": "success",
  "statusCode": 200,
  "data": {
    "id": "z_dBQc-tkL7Ext04ifOhw",
    "kind": "trustDeed",
    "storagePath": "extracts/files/serviceUid123/entities/trace456/docId789",
    "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-19T02:32:28.899Z"],
    "size": 245678,
    "createdAt": 1737254548899,
    "updatedAt": 1737254548899,
    "createdTime": "19/01/2026 02:32:28",
    "updatedTime": "19/01/2026 02:32:28",
    "download": {
      "downloadUrl": "https://storage.googleapis.com/...",
      "expiresAt": 1737255448899
    }
  },
  "message": "Document details retrieved successfully.",
  "help": null,
  "error": null
}

Document types reference

The kind field specifies the type of document being uploaded. Common document types by entity category:

Trust documents

Name
trustDeed
Type
string
Description
Trust deed document (typically required).
Name
signedTrustDeed
Type
string
Description
Signed trust deed.
Name
listOfBeneficiaries
Type
string
Description
List of trust beneficiaries.
Name
unitRegister
Type
string
Description
Unit register for unit trusts.
Name
deedOfVariationForChangeOfTrustee
Type
string
Description
Deed of variation for trustee changes.
Name
deedOfVariationForChangeOfTrustName
Type
string
Description
Deed of variation for trust name changes.
Name
disclosureCertificate
Type
string
Description
Disclosure certificate.
Name
willThatEstablishedTheTrust
Type
string
Description
Will that established the trust.
Name
other
Type
string
Description
Other trust-related document.

Company documents

Name
certificateOfIncorporation
Type
string
Description
Certificate of incorporation.
Name
companyConstitution
Type
string
Description
Company constitution.
Name
financialStatement
Type
string
Description
Financial statement.
Name
shareholderAgreement
Type
string
Description
Shareholder agreement.
Name
other
Type
string
Description
Other company-related document.

Documents

Overview

When to use each endpoint

Add new document

Upload methods

Required attributes

Optional attributes

Request

Response

Upload requested document

Path parameters

When to use

Request

remainingActions example

List documents

Path parameters

Response fields

Request

Response

Get document

Path parameters

Download URL

Error responses

Request

Response

Document types reference

Trust documents

Company documents

File constraints

Supported formats

Size limits