Invoices (Public API)

Read invoices ingested from your accounting provider (Yooz, etc.). Unlike the invoices embedded in a ticket payload, this resource also exposes invoices not yet associated to a ticket. Read-only.

The invoice model

• id — Bob! Desk invoice id
• provider — accounting provider (e.g. yooz)
• invoice_platform_id — id of the document in the provider (PA id)
• number — invoice reference
• issue_date / due_date — ISO 8601 dates
• currency — ISO currency code
• amounts — { ht, tva, ttc } (excluding tax / VAT / including tax)
• supplier — { name, siret }
• state — canonical state (ticket_unmatched, linked, ...)
• ticket_id — linked ticket id, or null
• supplier_id — resolved Bob! Desk contractor id, or null
• created_at / updated_at — ISO 8601 dates

List invoices

GET /api/v3.0/invoices

Optional query parameters

• association — unmatched | linked | all (default all). Use unmatched to list invoices awaiting ticket association (state = ticket_unmatched).
• issued_after / issued_before — filter on issue_date (timestamp in ms)
• created_after / created_before / updated_after / updated_before — timestamp in ms
• provider — exact match (e.g. yooz)
• supplier_siret — exact match
• number — exact match
• invoice_platform_id — exact match
• cursor — id of the last item of the previous page
• limit — page size, 1..200 (default 50)

curl -G https://api.bob-desk.com/api/v3.0/invoices \
  -H "Authorization: Bearer {token}" \
  -d association="unmatched" \
  -d limit="50"

{
  "cursor": "64a1f3c89ab7e72a4fb4ae03",
  "invoices": [
    {
      "id": "64a1f3c89ab7e72a4fb4ae01",
      "provider": "yooz",
      "invoice_platform_id": "YZ-2024-00871",
      "number": "FA-2024-00871",
      "issue_date": "2024-03-12T00:00:00.000Z",
      "due_date": "2024-04-12T00:00:00.000Z",
      "currency": "EUR",
      "amounts": { "ht": 1000.0, "tva": 200.0, "ttc": 1200.0 },
      "supplier": { "name": "ACME", "siret": "12345678900011" },
      "state": "ticket_unmatched",
      "ticket_id": null,
      "supplier_id": null,
      "created_at": "2024-03-12T08:00:00.000Z",
      "updated_at": "2024-03-12T08:00:00.000Z"
    }
  ]
}

To paginate, pass the id of the last item in the current page as the cursor parameter of the next request. When the response returns an empty invoices array and cursor is null, you have reached the end of the list.

Retrieve an invoice

GET /api/v3.0/invoices/:id

curl https://api.bob-desk.com/api/v3.0/invoices/64a1f3c89ab7e72a4fb4ae01 \
  -H "Authorization: Bearer {token}"

Returns { "invoice": { ... } }, or 404 if the invoice does not exist or belongs to another account.