Find invoices by document number
Scope: sales:invoices.read https://api.alladdin.com/api/v2/invoices/find-by-number
Returns invoices in your account whose document number matches the given value.
The match is fuzzy autocomplete: partial prefixes (e.g. F260) return all invoices that start with that token, and minor typos are tolerated. Results are scored by relevance and limited to the authenticated account. Draft, deleted and cancelled invoices are excluded.
Results are cursor-paginated: the response includes a cursor value and a has_more boolean. Pass the cursor to the next request to fetch the following page.
Parameters
Query parameters
document_number string required
Document number to look up. Supports prefixes (e.g. F260) and tolerates minor typos.
limit integer optional = 50
Maximum number of invoices to return per page.
cursor string optional
Pagination cursor returned by the previous response. Omit to start from the first page.
Request
import requests
url = "https://api.alladdin.com/api/v2/invoices/find-by-number?document_number=value&limit=50&cursor=value"
headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Accept": "application/json",
}
response = requests.get(url, headers=headers)
print(response.json())Responses
Response
{
"items": [
{
"id": "507f1f77bcf86cd799439011",
"document_number": "INV-0001",
"contact_id": "507f1f77bcf86cd799439011",
"contact_name": "Acme Corp",
"description": "string",
"date": "2024-01-15",
"due_date": "2024-02-15",
"subtotal": "100.00",
"discount": "0",
"total": "121.00",
"tax": "21.00",
"currency": "EUR",
"status": "pending",
"tags": [
"string"
],
"lines": [
{
"line_id": "...",
"name": "...",
"description": "...",
"price": "...",
"units": "...",
"discount": "...",
"tax": "...",
"taxes": "...",
"tags": "...",
"product_id": "...",
"variant_id": "...",
"service_id": "...",
"sku": "...",
"weight": "...",
"cost_price": "...",
"account": "...",
"project_id": "...",
"retention": "...",
"unit_type": "...",
"supplied": "..."
}
],
"payment_method_id": "string",
"payments_total": "0",
"payments_pending": "121.00"
}
],
"has_more": false,
"cursor": "string"
}Success responses
200 Invoices matching the document number application/json object items[] object[] id string
Unique identifier of the document
document_number string | null
Sequential number assigned to the document
contact_id string | null
Identifier of the contact associated with this document
contact_name string | null
Name of the contact associated with this document
description string | null
Free-text description of the document
date string<date> | null
Issue date of the document in ISO 8601 format
due_date string<date> | null
Payment due date in ISO 8601 format
subtotal string
Sum of all line amounts before tax and discounts, as a decimal string
discount string
Total discount applied to the document, as a decimal string
total string
Final amount including taxes and discounts, as a decimal string
tax string
Total tax amount, as a decimal string
currency string
ISO 4217 currency code
status string
Current status of the document
Enum: failed completed pending partial cancelled tags[] string[]
List of tags attached to the document
lines[] object[]
Line items included in the document
payment_method_id string | null
Identifier of the default payment method for this invoice
payments_total string
Total amount already paid, as a decimal string
payments_pending string
Remaining amount to be paid, as a decimal string
has_more boolean cursor string | null
Opaque cursor to pass as ?cursor= to fetch the next page. Null on the last page.
Error responses
400 Bad request application/json 401 Invalid or missing API key application/json 403 Insufficient permissions application/json 429 Rate limit exceeded application/json