Document API

With the Document API you upload documents to a channel, retrieve the processed data and tell Workist whether the import into your system worked. All document types offer the same operations.

The complete schemas of all requests and responses are in the Swagger UI. This page describes how to use the API.

Basics

• Base URL: https://api.workist.com/v1 (equivalent: https://api.workist.com/api/v1).
• No trailing slash. GET /orders works, GET /orders/ returns 404.
• Authentication: Every call carries the header Authorization: Bearer <API key>. The Quickstart explains how to create a key.
• Channels: An API key only sees the channels it has been granted. The API does not return documents of other channels.
• Format: Responses are JSON. Send uploads as multipart/form-data and all other requests as JSON.
• Channel delivery method: If your system pulls the results through the API, set the delivery method to API under Upload in the channel. Otherwise Workist also transfers the results via SFTP, and successfully transferred documents no longer appear under imported=false.

Resources

Document type	Resource
Orders	/orders
Invoices	/invoices
Order confirmations	/order-confirmations
Requests for quotation	/rfq
Delivery notes	/delivery-notes
Lists of services	/list-of-services

Operations

Every resource offers the same seven operations. Replace {resource} with the path from the table above, e.g. /orders.

Method	Path	Purpose
GET	/{resource}	List documents (paginated, filterable)
GET	/{resource}/{id}	Get one document
POST	/{resource}	Upload a file to a channel
DELETE	/{resource}/{id}	Delete a document
PATCH	/{resource}/{id}/meta	Set sender and subject
PUT	/{resource}/{id}/mark_imported	Report the result of the import into your system
PUT	/{resource}/{id}/assign_user	Assign the document to a user
POST	/list-of-services/{id}/generate-x94	Generate a GAEB X94 offer file from an X83 list of services

Typical flow

1. Documents reach the channel by email, through the Workbench or via POST /{resource}.
2. Your system regularly requests all finished documents that have not been handed over yet, e.g. GET /orders?finished=true&imported=false, and reads every page (see Pages).
3. For each document your system imports the data and reports the result with PUT /orders/{id}/mark_imported: SUCCEEDED with your document number, or FAILED with the error message.
4. Reported documents no longer appear in the request from step 2. Documents reported as FAILED come back once a user has corrected and finished them in the Workbench (see Report the import).

Instead of polling, you can have a webhook notify you when a document is finished and then retrieve it.

Retrieve documents

Filters

GET /{resource} accepts these query parameters:

Parameter	Meaning
channel	Channel ID. Only documents of this channel.
assistance_needed	true: only documents waiting for assistance in the Workbench. false: all others.
finished	true: finished documents that were not discarded. false: documents not finished yet.
imported	true: handed over successfully (feedback SUCCEEDED or a successful transfer via SFTP, AS2 or ERP integration). false: not handed over successfully yet. Unless you set import_failed, import_failed=false applies.
import_failed	true: handover failed (e.g. feedback FAILED). false: all others.
created_by	Email address or ID of the user who uploaded the document.
assisted_by	Email address or ID of the user who assisted the document.
date_from	Created at or after this time, ISO 8601 (YYYY-MM-DDTHH:MM:SSZ).
date_to	Created at or before this time, ISO 8601.
show_unfinished_data	true: fill data for documents that are still being processed. Default: false.
page	Page number, starting at 1.
page_size	Entries per page, at most 10.

GET /{resource}/{id} also accepts show_unfinished_data.

Pages

The list returns at most 10 documents per page, oldest first. The response has this shape:

{
  "total_count": 37,
  "next": "https://api.workist.com/v1/orders?finished=true&imported=false&page=2",
  "previous": null,
  "items": [ ... ]
}

• Call next until it is null. If you only read the first page, you miss documents.
• If you report documents while paging, they drop out of the imported=false filter and the following pages shift. In that case, request the first page again and again until items is empty.

Record

Every document in items and every single request has these fields:

Field	Content
id	Document ID (UUID).
channel	Channel ID.
status	Processing status, see Status.
sender	Sender, e.g. the sender of the email.
subject	Email subject or file name.
created_at	Time the document was received.
updated_at	Time of the last change.
created_by	User who uploaded the document (first_name, last_name, email).
assigned_to	Assigned user.
assisted_by	User who assisted the document.
assisted_at	Time of assistance.
delivered_at	Time of the successful transfer via SFTP, AS2 or ERP integration.
finished_at	Time the document was finished.
imported_at	Time your system confirmed the import with SUCCEEDED.
email_file_url	Link to the original email, if the document came by email.
input_file_url	Link to the processed file.
input_file_name	Original file name.
classified_files	Other attachments of the same email, with file_name, classification and url.
additional_file_urls	Links to additional files, if any.
workbench_url	Link to the document in the Workbench.
external_reference	Reference from the last feedback, e.g. your document number.
external_status	Status from the last feedback.
external_message	Message from the last feedback, e.g. an error message.
data	The extracted document data, see Document data.

File links are valid for at most 30 minutes. Download the files right after the request, or request the document again to get new links.

Status

status	Meaning
PENDING	Being processed.
ON_HOLD	Put on hold in the Workbench.
ASSISTANCE_NEEDED	Waiting for assistance in the Workbench.
ASSISTED	Assisted, processing continues.
FINISHED	Finished.
DELIVERED	Transferred via SFTP, AS2 or ERP integration.
IMPORTED	Your system confirmed the import with SUCCEEDED.
FAILED	Processing or handover failed, including after feedback FAILED.
REJECTED	The file could not be read.
DISCARDED	Discarded.
DELETED	Deleted. The API does not return deleted documents.

Document data

data holds the header fields of the document and the line items under line_items (for lists of services under positions). The Swagger UI shows the field names per document type.

• Only fields enabled in the channel carry values. All other fields are null.
• As long as a document has been neither assisted nor finished, data is empty ({}). With show_unfinished_data=true you get the current intermediate state.
• Quantities, prices and dates are text, as shown in the Workbench.

Upload a document

POST /{resource} with multipart/form-data:

Field	Required	Content
channel	Yes	ID of the channel that processes the document.
file	Yes	The file.
user	No	Email address or ID of a user who is recorded as the uploader.

• Channel ID: It is in the Workbench address bar when the channel is open (…/channels/<channel ID>), and in the channel field of every document of that channel. The channel must match the document type of the resource.
• File types: BMP, CSV, DOC, DOCX, EML, HTML, JPEG, ODS, PDF, PNG, RTF, TIFF, TXT, XLS, XLSM, XLSX and XML. Workist unpacks ZIP archives, Outlook messages (MSG) and winmail.dat and processes their content.
• Response: 201 with the new document. If one file results in several documents (e.g. an email with several attachments or a ZIP archive), the response only contains the first. Find the others with GET /{resource}.

Report the import

With PUT /{resource}/{id}/mark_imported you report whether your system took over the document. All fields are optional; without a body, SUCCEEDED applies.

Field	Content
status	SUCCEEDED (default): import succeeded, final. FAILED: import rejected, the document goes back to the Workbench. PENDING: handover still open.
external_reference	Reference of the document in your system, e.g. the sales order number.
external_status	Status of the document in your system.
external_message	Free text, e.g. your system's error message.

{
  "status": "FAILED",
  "external_reference": "",
  "external_status": "rejected",
  "external_message": "Article 4711 is blocked"
}

Rules:

• Only finished documents can be reported. Otherwise the API answers 400 with Record not finished yet.
• SUCCEEDED is final. The API rejects any further feedback for the same document with 400 and Record already successfully delivered.
• PENDING keeps the document in the imported=false request, e.g. when your system has accepted it but not booked it yet.
• Each feedback overwrites external_reference, external_status and external_message of the previous one.

What happens after FAILED

1. The document gets the status FAILED and no longer counts as finished. It appears in the list of open documents in the Workbench again.
2. When users open it, they see the notice "Your system rejected the document with the following response:" with the reference, status and message from your feedback.
3. A user clicks Reopen for assistance, corrects the data and finishes the document, or discards it with Discard.
4. Once finished again, the document reappears in GET /{resource}?finished=true&imported=false, and your system can import it again.

So write an understandable cause into external_message. It is what your colleagues read in the Workbench.

More operations

Set sender and subject

PATCH /{resource}/{id}/meta sets sender and subject, e.g. when you upload files from your own mailbox. Only the fields you send are changed.

Field	Content
sender	Sender, e.g. the sender of the original email.
subject	Subject, e.g. the subject of the original email.

Assign a user

PUT /{resource}/{id}/assign_user with {"user": "<email address or ID>"} assigns the document to a user of your organisation. The API rejects unknown users with 400 and {"user": ["User does not exist."]}.

Delete a document

DELETE /{resource}/{id} deletes the document and answers 204. The API no longer returns the document afterwards.

Generate GAEB X94

For lists of services that arrived as a GAEB X83 file, POST /list-of-services/{id}/generate-x94 generates an X94 offer file. You send your prices per position and your supplier data, and Workist returns the XML file.

• items (required): a list with one entry per position. source_id is the GAEB ID of the position and must match a position of the list of services. Optional: article_number, article_characteristics (normal, alternate or provis), quantity, unit, vat, net_price, price_basis, offer_price, price_basis_unit, ean, article_description.
• supplier_info (required): id_no, tax_no, reg_no and address with name1, street, p_code, city, country. All sub-fields are optional.
• Response: 200 with the X94 file (application/xml) as a download.
• Errors: 400 with {"error": "...", "message": "..."}, e.g. when the document is not a valid X83 file or a source_id does not match.

Errors

HTTP status	Cause	Response
400	Invalid request	{"detail": "<message>"} or per field {"<field>": ["<message>"]}, e.g. {"channel": ["Channel does not exist"]} or {"file": ["Unsupported file type"]}
401	API key missing, unknown or expired	{"detail": "Authentication credentials were not provided."}, {"detail": "Invalid token"} or {"detail": "Integration has expired"}
404	Document not found, channel not granted to the key, page out of range, or path with a trailing /	{"detail": "<message>"}

An expired key only works again after you change or remove its expiration date in the Workbench.