Documents
List and retrieve documents with financial details and recipient info.
Documents API
Read-only endpoints to list and retrieve documents (proposals, invoices, contracts, quotes). Requires an API token with documents.view ability. Financial amounts are returned in the smallest currency unit (e.g., cents).
List Documents
GET /api/v1/documents — Permission: documents.view
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
type | string | No | Filter by document type (e.g., invoice, proposal, contract, quote) |
status | string | No | Filter by status (e.g., draft, sent, viewed, signed, paid) |
search | string | No | Search by document number or title |
per_page | integer | No | Results per page, 1–100 (default: 25) |
Example Request
curl -X GET "https://your-domain.com/api/v1/documents?type=invoice&status=sent&per_page=10" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"const response = await fetch("https://your-domain.com/api/v1/documents?type=invoice&status=sent&per_page=10", {
headers: {
"Authorization": "Bearer YOUR_API_TOKEN",
"Accept": "application/json"
}
});
const data = await response.json();$ch = curl_init('https://your-domain.com/api/v1/documents?type=invoice&status=sent&per_page=10');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_API_TOKEN',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);import requests
response = requests.get(
"https://your-domain.com/api/v1/documents?type=invoice&status=sent&per_page=10",
headers={
"Authorization": "Bearer YOUR_API_TOKEN",
"Accept": "application/json"
}
)
data = response.json()Example Response
{
"data": [
{
"id": 101,
"type": "invoice",
"number": "INV-0042",
"title": "March Services",
"reference": "PO-2025-001",
"status": "sent",
"recipient": {
"type": "contact",
"id": 1,
"name": "Jane Doe"
},
"currency": "usd",
"subtotal": 150000,
"discount_amount": 0,
"tax_amount": 15000,
"total": 165000,
"amount_paid": 0,
"amount_due": 165000,
"issued_at": "2025-03-15T00:00:00.000000Z",
"due_at": "2025-04-14T00:00:00.000000Z",
"sent_at": "2025-03-15T10:30:00.000000Z",
"viewed_at": null,
"signed_at": null,
"paid_at": null,
"created_at": "2025-03-14T09:00:00.000000Z",
"updated_at": "2025-03-15T10:30:00.000000Z"
}
],
"meta": { "current_page": 1, "last_page": 1, "per_page": 10, "total": 1 },
"links": { "first": "...", "last": "...", "prev": null, "next": null }
}Get Document
GET /api/v1/documents/{id} — Permission: documents.view
Retrieve a single document with its recipient details and financial summary.
Example Request
curl -X GET "https://your-domain.com/api/v1/documents/101" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"const response = await fetch("https://your-domain.com/api/v1/documents/101", {
headers: {
"Authorization": "Bearer YOUR_API_TOKEN",
"Accept": "application/json"
}
});
const data = await response.json();$ch = curl_init('https://your-domain.com/api/v1/documents/101');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_API_TOKEN',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);import requests
response = requests.get(
"https://your-domain.com/api/v1/documents/101",
headers={
"Authorization": "Bearer YOUR_API_TOKEN",
"Accept": "application/json"
}
)
data = response.json()Returns the same shape as a single item in the list response.
Financial Fields
| Field | Type | Description |
|---|---|---|
subtotal | integer | Sum of line items before discounts and tax (in cents) |
discount_amount | integer | Total discount applied (in cents) |
tax_amount | integer | Total tax applied (in cents) |
total | integer | Final total after discounts and tax (in cents) |
amount_paid | integer | Total amount paid so far (in cents) |
amount_due | integer | Remaining balance (in cents) |
Was this article helpful?