Documents

The documents endpoints let you list and retrieve the documents held on file for your account — such as Letters of Authorisation (LOAs), trademark registrations, and other supporting files. Results are always scoped to the client(s) your API key represents.

Pagination

The list endpoint uses page-based pagination. Use the limit parameter to control page size and the page parameter to select the page number (1-indexed). The response paging object reports total, totalPages, and hasMore so you can iterate until hasMore is false.

List Documents

Returns a paginated list of documents for the client(s) your API key is authorised for.

Endpoint

GET /v1/documents

Parameters

Parameter	Type	Required	Description
`clientId`	`string`	No	Restrict results to a single client ID. Must be a client your API key is authorised for. Defaults to all clients on the key.
`docType`	`string`	No	Filter by document type. Comma-separated list accepted. One or more of `loa`, `trademark_registration`, `exec_loa`, `file`. See Document Types.
`loaType`	`string`	No	Filter LOA documents by how they were provided. One of `loa_file`, `loa_digital`.
`executiveId`	`string`	No	Filter documents associated with a specific executive.
`q`	`string`	No	Free-text search across document metadata (e.g. file name).
`sortBy`	`string`	No	Field to sort by. One of `createdAt`, `updatedAt`, `docType`, `id`.
`sortDir`	`string`	No	Sort direction. One of `asc`, `desc`.
`latestOnly`	`boolean`	No	When `true`, returns only the most recent document of each type.
`excludeDeleted`	`boolean`	No	When `true`, omits deleted documents.
`limit`	`integer`	No	Maximum number of documents to return per page. Must be from `1` to `200`. Defaults to `50`.
`page`	`integer`	No	Page number to return (1-indexed). Must be `1` or greater. Defaults to `1`.

Authorisation

Passing a clientId your API key is not authorised for returns 401 with Unauthorized. Please ensure client ID is valid..

Parameter validation

limit and page must be whole numbers within the ranges above, boolean flags must be true or false, and enum parameters must use one of the accepted values. Invalid values return 400 with a message describing the offending parameter.

Request Example

cURLPythonNode.js

curl -X GET -G 'https://capi.phishfort.com/v1/documents' \
  -H 'accept: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d 'docType=loa' \
  -d 'sortBy=updatedAt' \
  -d 'sortDir=desc' \
  -d 'limit=25'

import requests

response = requests.get(
    "https://capi.phishfort.com/v1/documents",
    headers={
        "accept": "application/json",
        "x-api-key": "YOUR_API_KEY",
    },
    params={
        "docType": "loa",
        "sortBy": "updatedAt",
        "sortDir": "desc",
        "limit": 25,
    },
)
print(response.json())

const params = new URLSearchParams({
  docType: "loa",
  sortBy: "updatedAt",
  sortDir: "desc",
  limit: "25",
});

const response = await fetch(
  `https://capi.phishfort.com/v1/documents?${params}`,
  {
    headers: {
      accept: "application/json",
      "x-api-key": "YOUR_API_KEY",
    },
  }
);
const data = await response.json();
console.log(data);

Response Example

The data field is an array of DocumentStructure's. The paging object reports the current page window and the total number of matching documents.

{
    "message": "success",
    "data": [
        {
            "id": "doc-abc123",
            "clientId": "0Xp5voyA4y5xYNoufOVC",
            "client": {
                "id": "0Xp5voyA4y5xYNoufOVC",
                "name": "Example Client",
                "parentClientId": null
            },
            "docType": "loa",
            "fileName": "example-loa.pdf",
            "uploadedBy": {
                "id": "user-abc123",
                "email": "alice@exampleclient.com",
                "name": "Alice",
                "surname": "Smith"
            },
            "createdAt": "2026-01-01T00:00:00.000Z",
            "updatedAt": "2026-01-03T00:00:00.000Z"
        }
    ],
    "paging": {
        "page": 1,
        "limit": 25,
        "count": 1,
        "total": 1,
        "totalPages": 1,
        "hasMore": false
    }
}

Fetching the Next Page

To fetch the next page of results, increment the page parameter until paging.hasMore is false:

curl -X GET -G 'https://capi.phishfort.com/v1/documents' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d 'limit=25' \
  -d 'page=2'

Get a Single Document

Returns the metadata for a single document, along with a short-lived signedUrl you can use to download the file.

Endpoint

GET /v1/documents/{documentId}

Path Parameters

Parameter	Type	Required	Description
`documentId`	`string`	Yes	The ID of the document to retrieve.

Not found

If the document does not exist, or belongs to a client your API key is not authorised for, the request returns 404 with Document not found..

Request Example

cURLPythonNode.js

curl -X GET 'https://capi.phishfort.com/v1/documents/doc-abc123' \
  -H 'accept: application/json' \
  -H 'x-api-key: YOUR_API_KEY'

import requests

response = requests.get(
    "https://capi.phishfort.com/v1/documents/doc-abc123",
    headers={
        "accept": "application/json",
        "x-api-key": "YOUR_API_KEY",
    },
)
print(response.json())

const response = await fetch(
  "https://capi.phishfort.com/v1/documents/doc-abc123",
  {
    headers: {
      accept: "application/json",
      "x-api-key": "YOUR_API_KEY",
    },
  }
);
const data = await response.json();
console.log(data);

Response Example

The data field is a DocumentStructure with an added signedUrl for downloading the file.

{
    "message": "success",
    "data": {
        "id": "doc-abc123",
        "clientId": "0Xp5voyA4y5xYNoufOVC",
        "client": {
            "id": "0Xp5voyA4y5xYNoufOVC",
            "name": "Example Client",
            "parentClientId": null
        },
        "docType": "loa",
        "fileName": "example-loa.pdf",
        "uploadedBy": {
            "id": "user-abc123",
            "email": "alice@exampleclient.com",
            "name": "Alice",
            "surname": "Smith"
        },
        "createdAt": "2026-01-01T00:00:00.000Z",
        "updatedAt": "2026-01-03T00:00:00.000Z",
        "signedUrl": "https://storage.googleapis.com/.../example-loa.pdf?..."
    }
}

Signed URLs are temporary

The signedUrl is a time-limited download link. Fetch it fresh when you need to download the file rather than storing it long term.

Get a Document Download URL

Returns a short-lived signed download URL for a document, without the surrounding metadata. Useful when you already hold the document metadata and just need a fresh download link.

Endpoint

GET /v1/documents/{documentId}/signed-url

Path Parameters

Parameter	Type	Required	Description
`documentId`	`string`	Yes	The ID of the document to generate a download URL for.

Not found

If the document does not exist, or belongs to a client your API key is not authorised for, the request returns 404 with Document not found..

Request Example

cURLPythonNode.js

curl -X GET 'https://capi.phishfort.com/v1/documents/doc-abc123/signed-url' \
  -H 'accept: application/json' \
  -H 'x-api-key: YOUR_API_KEY'

import requests

response = requests.get(
    "https://capi.phishfort.com/v1/documents/doc-abc123/signed-url",
    headers={
        "accept": "application/json",
        "x-api-key": "YOUR_API_KEY",
    },
)
print(response.json())

const response = await fetch(
  "https://capi.phishfort.com/v1/documents/doc-abc123/signed-url",
  {
    headers: {
      accept: "application/json",
      "x-api-key": "YOUR_API_KEY",
    },
  }
);
const data = await response.json();
console.log(data);

Response Example

{
    "message": "success",
    "data": {
        "url": "https://storage.googleapis.com/.../example-loa.pdf?..."
    }
}