Documents

Documents are your agency's library: written Markdown documents, PDFs and other files. Reading needs documents:read; creating, changing, sharing and attaching need documents:write.

Every document route needs an active Fondaro plan. Without one, even a read answers 403 with SUBSCRIPTION_REQUIRED.

• A document starts private to its creator and the agency's admins. Sharing it makes it visible to the whole agency and gives it a public link.
• Only a document's owner or an admin can change or share it. A private document someone else made stays invisible to you, even when it is attached to a lead you can reach: an attachment is not a grant.
• You can create and edit Markdown documents only. A PDF or other uploaded file is described by its metadata; the API never returns file bytes and does not upload files.

A document you cannot reach answers 404 with NOT_FOUND, the same as one that does not exist.

List document folders

GET /v1/document-folders

Every folder of the library, with how many items you can see directly inside each. Pass a folder id as folderId to list its documents.

curl https://api.fondaro.com/v1/document-folders \  -H "Authorization: Bearer $FONDARO_API_KEY"

{  "data": [{ "id": "3f6c2a10-0000-4000-8000-000000000018", "name": "Test folder", "parentId": null, "documentCount": 1 }],  "hasMore": false}

List documents

GET /v1/documents

Documents in the library, most recently changed first. Each row carries its public link while it is shared and live.

curl "https://api.fondaro.com/v1/documents?limit=2" \  -H "Authorization: Bearer $FONDARO_API_KEY"

{  "data": [    {      "id": "3f6c2a10-0000-4000-8000-000000000019",      "title": "Untitled document",      "kind": "markdown",      "visibility": "private",      "sizeBytes": null,      "createdBy": "user_2abcDEF1234567890ghiJKL",      "assigneeIds": [],      "shareUrl": null,      "attachedLeadCount": 0,      "attachedListingCount": 0,      "folderId": null,      "createdAt": "2026-10-01T18:07:28.328Z",      "updatedAt": "2026-10-01T18:07:28.328Z"    }  ],  "hasMore": true,  "nextOffset": 2,  "total": 4}

Paging is by offset, with an exact total.

Create a Markdown document

POST /v1/documents

Creates a Markdown document in the library. It starts private. Accepts an Idempotency-Key header.

curl -X POST https://api.fondaro.com/v1/documents \  -H "Authorization: Bearer $FONDARO_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "title": "Viewing checklist", "body": "# Checklist\n\nWritten through the Fondaro API." }'

The 201 response is the document:

{  "id": "3f6c2a10-0000-4000-8000-000000000007",  "title": "Viewing checklist",  "kind": "markdown",  "visibility": "private",  "createdBy": "user_2abcDEF1234567890ghiJKL",  "shareUrl": null,  "attachedLeadCount": 0,  "folderId": null,  "createdAt": "2026-10-04T12:02:29.454Z",  "updatedAt": "2026-10-04T12:02:29.454Z",  "body": "# Checklist\n\nWritten through the Fondaro API.",  "truncated": false,  "shareRevokedAt": null,  "shareExpiresAt": null,  "attachedLeadIds": [],  "attachedListingIds": []}

Get a document

GET /v1/documents/{documentId}

One document: its metadata and, for a written document, the whole Markdown body (truncated is false here). An uploaded file comes back as metadata only.

curl https://api.fondaro.com/v1/documents/3f6c2a10-0000-4000-8000-000000000007 \  -H "Authorization: Bearer $FONDARO_API_KEY"

The response is the document, in the shape shown above.

Update a document

PATCH /v1/documents/{documentId}

Changes the title, the Markdown body, or both. The body replaces the whole document, so include everything that should stay. Only the owner or an admin can change it, and only a Markdown document has an editable body.

curl -X PATCH https://api.fondaro.com/v1/documents/3f6c2a10-0000-4000-8000-000000000007 \  -H "Authorization: Bearer $FONDARO_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "body": "# Checklist\n\nEdited through the Fondaro API." }'

The response is the document with the new body and a later updatedAt.

Share a document

POST /v1/documents/{documentId}/share

Publishes the document behind a public link that anyone holding the URL can open, and returns it as shareUrl. Sharing also makes the document visible to everyone in your agency. Sharing again while the link is live returns the same URL. Only the owner or an admin can share.

curl -X POST https://api.fondaro.com/v1/documents/3f6c2a10-0000-4000-8000-000000000007/share \  -H "Authorization: Bearer $FONDARO_API_KEY" \  -H "Content-Type: application/json" \  -d '{}'

The response is the document with "visibility": "public" and shareUrl set to a link such as https://www.fondaro.com/d/aB3dE5fG7hJ9kL1mN3pQ5r.

Revoke a document's public link

DELETE /v1/documents/{documentId}/share

Takes the public link down: anyone holding the URL can no longer open it, and sharing again makes a different URL. The document stays in the library and stays visible to your agency; it does not become private again.

curl -X DELETE https://api.fondaro.com/v1/documents/3f6c2a10-0000-4000-8000-000000000007/share \  -H "Authorization: Bearer $FONDARO_API_KEY"

The response is 204 with no body.

List a lead's documents

GET /v1/leads/{leadId}/documents

The documents attached to a lead, most recently attached first, with who attached each and when. At most 50, with no paging: hasMore is true when that limit was reached. You need access to the lead; a lead you cannot reach answers 404.

curl https://api.fondaro.com/v1/leads/1042/documents \  -H "Authorization: Bearer $FONDARO_API_KEY"

{  "data": [    {      "id": "3f6c2a10-0000-4000-8000-000000000007",      "title": "Viewing checklist",      "kind": "markdown",      "visibility": "private",      "sizeBytes": null,      "createdBy": "user_2abcDEF1234567890ghiJKL",      "attachedBy": "user_2abcDEF1234567890ghiJKL",      "attachedAt": "2026-10-04T12:02:30.924Z",      "updatedAt": "2026-10-04T12:02:30.356Z"    }  ],  "hasMore": false}

Attach a document to a lead

PUT /v1/leads/{leadId}/documents/{documentId}

Records that the document belongs with the lead, so it shows on the lead and in its timeline. You need access to both. Attaching twice is harmless and keeps the first receipt. Needs documents:write.

curl -X PUT https://api.fondaro.com/v1/leads/1042/documents/3f6c2a10-0000-4000-8000-000000000007 \  -H "Authorization: Bearer $FONDARO_API_KEY" \  -H "Content-Type: application/json" \  -d '{}'

The response is the document with attachedLeadCount of 1 and the lead in attachedLeadIds.

Detach a document from a lead

DELETE /v1/leads/{leadId}/documents/{documentId}

Removes the link between the document and the lead, and with it the receipt of who attached it. The document stays in the library. Detaching something already detached changes nothing.

curl -X DELETE https://api.fondaro.com/v1/leads/1042/documents/3f6c2a10-0000-4000-8000-000000000007 \  -H "Authorization: Bearer $FONDARO_API_KEY"

The response is 204 with no body.