Purchase Documents

Purchase documents connect a ticket to your purchasing system (Coupa, SAP Ariba, an ERP…). They are read with the ticket itself, in the purchases property of Get a ticket and of the Tickets List, and written with the endpoints of this page.

Rules and errors

Purchase documents are the procurement papers attached to a ticket: a purchase request (purchase_request), a purchase order (purchase_order) and a goods receipt (goods_receipt, which attests that the intervention was carried out; it is not an invoice validation). The sequence request → order → receipt is not enforced.

• A document is always issued by your own account, the buyer. The supplier is the contractor assigned to the ticket, frozen as soon as it is known; a purchase order is then visible to that supplier.
• Only the buyer can modify or delete a document. A supplier that received a purchase order gets 403.
• Nothing can be written while the ticket is a draft, canceled or declined for your account (409). Finished and closed tickets stay writable, so a goods receipt can be added after the intervention.
• At most 200 live documents per buyer and per ticket.
• Reading goes through purchases[] of Get a ticket and Tickets List. Every addition triggers the ticket.purchase_added webhook.

The write endpoints return the document as purchase, with id; in purchases[] of the ticket the same document is keyed by _id and carries source and s3_key in addition. Every error is returned as { "error": "...", "code": "..." }:

Create a purchase document

curl -X POST https://api.bob-desk.com/api/v3.0/tickets/:ticket_id/purchases \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "kind": "purchase_order",
    "reference": "PO-2026-00042",
    "source_system": "coupa",
    "quote_id": "63725f259ab7e72a4fb4ae69",
    "date": "2026-10-01T00:00:00.000Z",
    "amount": 1000
  }'

{
  "purchase": {
    "id": "68e0a1b29ab7e72a4fb4af01",
    "ticket_id": "63725f259ab7e72a4fb4ae69",
    "kind": "purchase_order",
    "buyer_company_id": "5d9b5b5b9ab7e72a4fb4ae69",
    "supplier_company_id": "5d973899ecb060003525ddec",
    "reference": "PO-2026-00042",
    "source_system": "coupa",
    "quote_id": "63725f259ab7e72a4fb4ae69",
    "purchase_order_id": null,
    "date": "2026-10-01T00:00:00.000Z",
    "amount": 1000,
    "document_id": null,
    "from_api": true,
    "created_at": "2026-10-01T08:00:00.000Z",
    "created_by": "5d9b5b5b9ab7e72a4fb4ae68",
    "updated_at": "2026-10-01T08:00:00.000Z",
    "updated_by": "5d9b5b5b9ab7e72a4fb4ae68",
    "editable": true
  },
  "created": true
}

Update a purchase document

curl -X PATCH https://api.bob-desk.com/api/v3.0/tickets/:ticket_id/purchases/:purchase_id \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "amount": 1250,
    "source_system": null
  }'

Delete a purchase document

curl -X DELETE https://api.bob-desk.com/api/v3.0/tickets/:ticket_id/purchases/:purchase_id \
  -H "Authorization: Bearer {token}"

Attach a file to a purchase document

curl -X POST https://api.bob-desk.com/api/v3.0/tickets/:ticket_id/purchases/:purchase_id/document \
  -H "Authorization: Bearer {token}" \
  -F "file=@/path/to/PO-2026-00042.pdf"

Recommended workflow for a purchasing integration

This is the workflow we recommend to raise a purchase in your purchasing system (Coupa, SAP Ariba, an ERP…) when a quote is validated in Bob! Desk, and to send the purchase documents back to the ticket.

1. Find the validated quotes. Every day, call GET /api/v3.0/tickets?status=validated and keep the quotes with validated: true. Deduplicate on quotes[]._id: one quote must raise only one purchase request. validated is a transient status (it ends as soon as the work is scheduled), so also run a weekly catch-up with GET /api/v3.0/tickets?updated_after={7 days ago, in milliseconds} and read quotes[].validated_at. Never call updated_after alone with a date far in the past.
2. Choose the requester. Raise the purchase request on behalf of the ticket's validated_by when it is set, otherwise of its creator. A contractor user does not exist in your purchasing system: the person on your side who validated the ticket carries the request.
3. Get the quote file. Get a ticket returns a download_url on each quote. From the list, pass quotes[].s3_key to Download link of a document. The signed links are served from documents.bob-desk.com: allow this host in your outgoing network rules.
4. Match the supplier. Store your supplier number in a custom field of the contractors and read it from fields on Contractors.
5. Send the purchase documents back. Create the purchase request, then the purchase order with Create a purchase document (with quote_id), and attach its PDF. Later, record the goods receipt with purchase_order_id. Creation is idempotent: sending the same document again is safe.
6. Follow the changes. Subscribe to the ticket.purchase_added webhook to be notified of each new purchase document.