# 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**

```bash
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**

```js
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`

```json
{
  "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](/api/#errors) in the overview.

## Related endpoints

- `POST /v1/leads/{lead_id}/files` · [Upload a file](/api/files/upload)