Upload a file

POST /v1/leads/{lead_id}/files

Adds one file to 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.

The body is multipart/form-data with exactly one part: the file, in a part named file, sent as a file (with a filename). Let your HTTP client set the Content-Type and its boundary.

The type is recognized from the file's content (its magic bytes): PDF, JPEG, PNG, WebP, HEIC or HEIF. The part's Content-Type and the file name's extension are ignored, so a renamed file of another type is rejected with 415. Image fields take images only, unless your team set the field to also accept files. The stored name is the part's filename without any directory or control characters, shortened to 200 characters (keeping its extension); without a usable name the file is called upload.<ext>, for example upload.pdf.

The file goes to the lead's main card in its campaign (never a linked card on another team's pipeline). A follow-through card shares its main card's files, as in DialEcho, so a member who sees the lead only through a follow-through card uploads to those same files. A field can hold several files and an upload never replaces one: to replace a file, upload the new one, then delete the old one. The file records the API key (by its prefix) as its uploader.

Retries are safe with the same Idempotency-Key: the same file (same lead, field, file name and content) answers 201 with the same file_id and stores nothing new. Using the key for anything else is 409 idempotency_conflict. Create a new key for every new upload.

Headers

Name	Type	Required	Description
Idempotency-Key	string	Yes	One key per upload, reused on its retries. 16 to 128 printable ASCII characters, no spaces (a UUID works).

Path parameters

Name	Type	Required	Description
lead_id	UUID	Yes	The lead.

Query parameters

Name	Type	Required	Description
field	string	Yes	Slug of a file or image custom field of the lead's campaign. Any other slug (unknown, deleted, another type or another campaign's field) is 422 unknown_field.

Body

Content type: multipart/form-data

Name	Type	Required	Description
file	file	Yes	The document or photo, sent as a file part with a filename. Empty files are rejected. Up to 10 MB (10,485,760 bytes). PDF, JPEG, PNG, WebP, HEIC or HEIF.

Response

Status: 201 Created

Name	Type	Description
file_id	UUID	The stored file. Keep it to delete the file later.
lead_id	UUID	The lead.
field	string	The custom field slug.
filename	string	The name the file was stored under.
content_type	string	The type DialEcho recognized, for example application/pdf.
size_bytes	integer	Size of the stored file.

Example request

curl

curl -X POST "https://development.agencydevworks.ai/v1/leads/aaaaaaaa-0000-4000-8000-000000000001/files?field=utility_bill" \
  -H "Authorization: Bearer dei_your_key" \
  -H "Idempotency-Key: 0f0f0f0f-0000-4000-8000-00000000abcd" \
  -F "file=@utility-bill.pdf"

JavaScript

import { openAsBlob } from "node:fs";

const form = new FormData();
form.append("file", await openAsBlob("utility-bill.pdf"), "utility-bill.pdf");

const response = await fetch("https://development.agencydevworks.ai/v1/leads/aaaaaaaa-0000-4000-8000-000000000001/files?field=utility_bill", {
  method: "POST",
  headers: {
    "Authorization": "Bearer dei_your_key",
    "Idempotency-Key": "0f0f0f0f-0000-4000-8000-00000000abcd",
  },
  body: form,
});
const data = await response.json();

Example response

Status: 201 Created

{
  "file_id": "55555555-0000-4000-8000-000000000001",
  "lead_id": "aaaaaaaa-0000-4000-8000-000000000001",
  "field": "utility_bill",
  "filename": "utility-bill.pdf",
  "content_type": "application/pdf",
  "size_bytes": 482133
}

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 does not exist or the key cannot reach it.
409	no_pipeline_card	The lead has no pipeline card. Nothing was stored.
409	idempotency_conflict	The Idempotency-Key was already used for a different upload. Nothing was stored.
413	file_too_large	The file is larger than 10 MB. Nothing was stored.
415	unsupported_media_type	The content is not a PDF, JPEG, PNG, WebP, HEIC or HEIF file, or is a PDF sent to an image-only field. Nothing was stored.
422	unknown_field	field is not a file or image custom field of the lead's campaign.
422	invalid_request	lead_id is not a UUID, field or Idempotency-Key is missing or malformed, or the file is empty or the body is not exactly one file part named file (these two carry an empty error.fields).
503	dependency_unavailable	The file could not be stored right now. Retry with the same Idempotency-Key.

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

Related endpoints

• DELETE /v1/leads/{lead_id}/files/{file_id} · Delete a file
• POST /v1/leads · Create or update a lead