BronID

Documents

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

Overview

Documents can be uploaded to a verification at any point during the verification lifecycle. There are two upload 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

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 will automatically remove the document from the remainingActions list.

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

Returns an array of document objects with their metadata. Each document includes:

  • Document ID and type
  • Upload status
  • File metadata (name, size, MIME type)
  • Timestamps

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

{
  "serviceUid": "5qA5Hq0n1JQTY2TASItxYXSRyND3",
  "trace": "DriJoJAkKk-YUBKFVXW7c",
  "path": "/v5/verifications/:trace/documents",
  "pathParams": {
    "trace": "DriJoJAkKk-YUBKFVXW7c"
  },
  "timestamp": "2026-01-19T02:35:00.000Z",
  "status": "success",
  "statusCode": 200,
  "data": [
    {
      "id": "z_dBQc-tkL7Ext04ifOhw",
      "kind": "trustDeed",
      "stakeholderId": null,
      "name": "trust-deed.pdf",
      "description": "Trust deed for My Company",
      "status": "current",
      "mimeType": "application/pdf",
      "size": 245678,
      "createdAt": 1737254548899,
      "updatedAt": 1737254548899
    },
    {
      "id": "abc123-document-id",
      "kind": "certificateOfIncorporation",
      "stakeholderId": null,
      "name": "certificate.pdf",
      "description": "Certificate of incorporation",
      "status": "current",
      "mimeType": "application/pdf",
      "size": 125000,
      "createdAt": 1737254600000,
      "updatedAt": 1737254600000
    }
  ],
  "message": "Documents retrieved successfully.",
  "help": null,
  "error": null
}
GET/v5/verifications/:trace/documents/:documentId

Get document

This endpoint allows you to retrieve a specific document's metadata and download URL.

Path parameters

  • Name
    trace
    Type
    string
    Description

    The unique identifier for the verification.

  • Name
    documentId
    Type
    string
    Description

    The unique identifier for the document.

Response fields

  • Name
    id
    Type
    string
    Description

    Unique document identifier.

  • Name
    kind
    Type
    string
    Description

    Document type/category.

  • Name
    stakeholderId
    Type
    string
    Description

    Reference to stakeholder (null for entity-level documents).

  • Name
    name
    Type
    string
    Description

    File name.

  • Name
    description
    Type
    string
    Description

    Human-readable description.

  • Name
    reason
    Type
    string
    Description

    Reason for the document.

  • Name
    status
    Type
    string
    Description

    Document status: current, error, deleted, or superseded.

  • Name
    mimeType
    Type
    string
    Description

    MIME type of the document.

  • Name
    size
    Type
    number
    Description

    File size in bytes.

  • Name
    timeline
    Type
    string[]
    Description

    Array of events/actions related to the document.

  • Name
    createdAt
    Type
    number
    Description

    Unix timestamp of creation.

  • Name
    updatedAt
    Type
    number
    Description

    Unix timestamp of last update.

  • Name
    download
    Type
    object
    Description

    Contains downloadUrl (signed URL) and expiresAt (Unix timestamp).

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",
    "stakeholderId": null,
    "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": "2026-01-19T02:32:28.899Z",
    "updatedTime": "2026-01-19T02:32:28.899Z",
    "download": {
      "downloadUrl": "https://storage.googleapis.com/...",
      "expiresAt": 1737255448899
    }
  },
  "message": "Document 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.

File constraints

Supported formats

  • Name
    application/pdf
    Type
    PDF
    Description

    PDF documents.

  • Name
    image/jpeg
    Type
    JPEG
    Description

    JPEG images.

  • Name
    image/png
    Type
    PNG
    Description

    PNG images.

Size limits

Maximum file size is 25 MB per document.

Was this page helpful?