GET /api/v1/files

Returns every file on one record, newest first. Requires the read:files scope (or * for full access).

Request

GET /api/v1/files?entity=contact&recordId=hs_contact_123 HTTP/1.1
Host: agentlyleads.com
Authorization: Bearer alk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Query parameters

Parameter	Required	Description
`entity`	Yes	The record type: `CONTACT`, `LEAD`, `DEAL`, `COMPANY`, `QUOTE`, `CONTRACT`, `TASK`, `NOTE`, `CASE`, `CAMPAIGN` or `OFFERING`. Case-insensitive
`recordId`	Yes	The record's agentlyleads ID, or its `externalId` where the record type has one

Response: 200

{
  "files": [
    {
      "id": "cmq3file0alk34567890",
      "entity": "CONTACT",
      "recordId": "cmq2cont0alk34567891",
      "kind": "attachment",
      "fileName": "signed-nda.pdf",
      "contentType": "application/pdf",
      "size": 184320,
      "createdAt": "2026-09-27T14:02:00.000Z"
    },
    {
      "id": "cmq3file1alk34567891",
      "entity": "CONTACT",
      "recordId": "cmq2cont0alk34567891",
      "kind": "attachment",
      "fileName": "business-card.jpg",
      "contentType": "image/jpeg",
      "size": 94208,
      "createdAt": "2026-09-20T09:41:00.000Z"
    }
  ]
}

A record with no files returns { "files": [] }. A record that does not exist in this workspace returns 404, for example { "error": "Contact not found." }.

The list is not paginated. It returns every file on the record in one response.

Offerings

An offering's list contains both its documents and its product photos, sorted together by date. Tell them apart with kind:

{
  "files": [
    {
      "id": "cmq4odoc0alk34567890",
      "entity": "OFFERING",
      "recordId": "cmq2offr0alk34567890",
      "kind": "document",
      "fileName": "spec-sheet.pdf",
      "contentType": "application/pdf",
      "size": 412001,
      "createdAt": "2026-09-27T10:15:00.000Z"
    },
    {
      "id": "cmq4oimg0alk34567890",
      "entity": "OFFERING",
      "recordId": "cmq2offr0alk34567890",
      "kind": "image",
      "fileName": "Front of pack",
      "contentType": "image/png",
      "size": 830112,
      "createdAt": "2026-09-26T16:02:00.000Z"
    }
  ]
}

Only photos that finished processing are listed. A photo still being imported, or one whose import failed, is left out.

Downloading

List entries carry no download link, so listing a record with many files stays cheap. To download one, pass its id to GET /api/v1/files/{id}.