Skip to main content
GET

List inbox incoming documents

Scope:inbox:inbox.read
https://api.holded.com/api/v2/inbox

Returns a cursor-paginated list of incoming documents in your inbox. Optional filters: `status` (comma-separated list of statuses: `new`, `processing`, `error`, `pending_to_verify`, `done`, `rejected`), `start_date`/`end_date` (ISO 8601 date range on creation date), `user_id` (comma-separated user IDs). Results are ordered by creation date descending (newest first). Pass `cursor` from the previous response to fetch the next page.

Parameters

Query parameters

cursorstringoptional

Opaque pagination cursor from the previous response

limitintegeroptional= 50

Number of items per page. Defaults to 50, maximum 200.

statusstringoptional

Comma-separated statuses to filter by (e.g. pending_to_verify,done)

start_datestring<date-time>optional

Filter documents created on or after this ISO 8601 date

end_datestring<date-time>optional

Filter documents created on or before this ISO 8601 date

user_idstringoptional

Comma-separated user IDs to filter by uploader

Request

python
import requests

url = "https://api.holded.com/api/v2/inbox?cursor=value&limit=50&status=value"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Accept": "application/json",
}

response = requests.get(url, headers=headers)
print(response.json())

Responses

Response

json
{
  "items": [
    {
      "id": "string",
      "status": "pending_to_verify",
      "origin": {
        "id": "string",
        "name": "string",
        "type": "upload",
        "source": "string"
      },
      "document_number": "string",
      "type": "invoice",
      "outcome": {
        "documentId": "string",
        "documentNumber": "string",
        "type": "string",
        "isDraft": false,
        "exportedAt": "2024-01-15T10:30:00Z",
        "attached": false
      },
      "date": "2024-01-15T10:30:00Z",
      "contact_name": "string",
      "total": "100,00",
      "file": {
        "filename": "string",
        "path": "string"
      },
      "thumbnail": "string",
      "signature": {
        "filename": "string",
        "path": "string"
      },
      "scanned_at": "string",
      "seen_at": "string",
      "errors": [
        "string"
      ],
      "draft": {
        "description": "string"
      }
    }
  ],
  "cursor": "string",
  "has_more": false
}

Success responses

200List of incoming documentsapplication/json
object
items[]object[]
idstring

Unique identifier of the incoming document

statusstring

Current status

Enum:newprocessingerrorpending_to_verifydonerejected
originobject

Origin metadata

document_numberstring | null

Document number extracted from the file

typestring | null

Document type

Enum:invoicesalesreceiptcreditnotepurchaseorderpurchaseshipmentsalesorderreceiptpurchaserefundestimatewaybillproformreceiptnoteinvoicerecurringpurchaserecurringpayrollpayrollrecurringamazonorderproductionorderinvoicingforecast
outcomeobject | null

Linked document outcome if the document has been processed

datestring<date-time>

Creation date in ISO 8601 format

contact_namestring | null

Name of the associated contact

totalstring | null

Total amount as decimal string

fileobject | null

Primary file associated with the document

thumbnailstring | null

Thumbnail URL (reserved for future use)

signatureobject | null

Certified digitization signature file

scanned_atstring | null

Date the document was scanned (ISO 8601)

seen_atstring | null

Date the document was first seen (ISO 8601)

errors[]string[]

List of error codes if the scan failed

draftobject

Draft metadata extracted from the document

cursorstring | null
has_moreboolean

Error responses

401Invalid or missing API keyapplication/json
403Insufficient permissionsapplication/json
429Rate limit exceededapplication/json