Scan Invoice Attachment
POST/api/purchase-invoices/:purchaseInvoice/attachments/:attachment/ocr
Start an OCR scan of a purchase invoice attachment. No request body.
purchase-orders:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Asynchronous — this queues a background scan and returns immediately. The attachment's ocr_status moves through processing and finishes as completed (with ocr_processed_at set) or failed (with ocr_error_message). Poll Get Attachment OCR Extraction or List Purchase Invoice Attachments to track progress. Scanning does not modify the invoice itself — use Apply OCR Extraction to Invoice to accept the results.
The scan extracts invoice header fields and line items from the document and matches them against the linked purchase order's product and cost lines.
Requirements and errors:
- Invoice OCR must be enabled in Settings, otherwise 422.
- Only PDF and image (JPEG/PNG) attachments can be scanned — 422 for other types.
- Archived invoices return 422.
- A scan already in progress for the attachment returns 409.
Requires the purchase-orders:write token scope.
Request
Responses
- 200
- 401
- 403
- 404
- 409
- 422
- 429
OK
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Not found — no record with the given identifier (or the route does not exist). Verify the ID before retrying.
Conflict
Response Headers
Unprocessable Entity
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.