Delete a file

DELETE /v1/leads/{lead_id}/files/{file_id}

Removes one file from a file or image custom field of the lead's pipeline card.

Scope: leads:write

Access: The key's member must also be allowed to see files.

Works exactly as deleting the file on the board: the stored file is deleted and disappears from the card's Custom Fields panel.

Only a file on the lead's main card, in a file or image custom field of its campaign, can be removed; a follow-through card shares those files, so a member who sees the lead only through one removes them the same way. Any other file_id (unknown, already removed, or another lead's file) is 404 not_found, so a retry after a timed-out request that did remove the file also answers 404: treat it as done.

If the stored file cannot be removed the request fails with 502 dependency_unavailable and the file stays on the card; retry the same request with backoff.

Path parameters

Name	Type	Required	Description
lead_id	UUID	Yes	The lead.
file_id	UUID	Yes	The file_id the upload returned.

Response

Status: 200 OK

Identifiers only, never the file's name or content.

Name	Type	Description
file_id	UUID	The removed file.
lead_id	UUID	The lead.
field	string	The custom field slug it was removed from.
deleted	boolean	Always true.

Example request

curl

curl -X DELETE "https://development.agencydevworks.ai/v1/leads/aaaaaaaa-0000-4000-8000-000000000001/files/55555555-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer dei_your_key"

JavaScript

const response = await fetch("https://development.agencydevworks.ai/v1/leads/aaaaaaaa-0000-4000-8000-000000000001/files/55555555-0000-4000-8000-000000000001", {
  method: "DELETE",
  headers: {
    "Authorization": "Bearer dei_your_key",
  },
});
const data = await response.json();

Example response

Status: 200 OK

{
  "file_id": "55555555-0000-4000-8000-000000000001",
  "lead_id": "aaaaaaaa-0000-4000-8000-000000000001",
  "field": "utility_bill",
  "deleted": true
}

Errors

HTTP	Code	When
403	insufficient_scope	The key does not have leads:write.
403	permission_denied	The key's member may not see files. Only for a lead they can see; any other lead is 404.
404	not_found	The lead or file does not exist, was already removed, belongs to another lead, or the key cannot reach the lead.
422	invalid_request	lead_id or file_id is not a UUID.
502	dependency_unavailable	The stored file could not be removed. It stays on the card; retry with backoff.

Every endpoint can also answer 401 invalid_api_key, 429 rate_limited and 503 dependency_unavailable. See Errors in the overview.

Related endpoints

• POST /v1/leads/{lead_id}/files · Upload a file