Documents REST API

All document operations use the REST API at /api/v2.

Permissions Required

Read operations (GET) require the DocumentObservation permission. Write operations (PUT, POST, and DELETE) require DocumentManagement. This applies to both single-document and batch endpoints.

For a guided walkthrough, see the Working with Documents guide.

Endpoints

Single document operations

Method	Endpoint	Description
PUT	/api/v2/organisations/{orgId}/documents/{docId}	Create or update a document
GET	/api/v2/organisations/{orgId}/documents/{docId}	Fetch a document
DELETE	/api/v2/organisations/{orgId}/documents/{docId}	Delete a document

PUT query parameters

Parameter	Description
upsert=true	Create the document if it doesn’t exist, update if it does
enableBaseOrgs=true	Auto-create organisations when Core ID doesn’t match an existing connection

Batch operations

Method	Endpoint	Description
POST	/api/v2/organisations/{orgId}/document-jobs/	Submit a batch of documents to upsert
DELETE	/api/v2/organisations/{orgId}/document-jobs/documents	Submit a batch of document IDs to delete
GET	/api/v2/organisations/{orgId}/document-jobs/	List all batch jobs
GET	/api/v2/organisations/{orgId}/document-jobs/{batchId}	Get batch job details
GET	/api/v2/organisations/{orgId}/document-jobs/{batchId}/result	Get batch job results
DELETE	/api/v2/organisations/{orgId}/document-jobs/{batchId}	Cancel a queued batch job

POST query parameters

Parameter	Description
enableBaseOrgs=true	Auto-create organisations when Core ID doesn’t match an existing connection
selfCoreId={value}	Set the location’s self Core ID for matching the occupant in the batch

A single upsert batch accepts up to 25,000 documents.

Batch delete request body

Send a JSON array of document IDs to delete:

["PO-2000", "PO-2001", "PO-2002"]

Batch job response

Both batch endpoints return the job record rather than the finished work:

Property	Type	Description
id	string	Batch job identifier, used with the job endpoints
createdAt	string	When the job was queued
status	string	Processing state of the job
completedAt	string	When the job finished, null while pending
documentCount	number	Documents in the job
errors	number	Documents that failed

Deletion is asynchronous. Poll GET /document-jobs/{batchId} for the job state, then GET /document-jobs/{batchId}/result for the outcome of each document. Each result entry reports Deleted, or Failed with a DocumentNotFound error when the ID doesn’t match a document at the location.

Document input schema

Property	Type	Required	Description
id	string	Yes	Unique document identifier
direction	string	Yes	Inbound or Outbound
occupant	OrgRef	*	The location organisation
offsite	OrgRef	*	The remote organisation
carrier	OrgRef	*	The transport company
loads	Load[]	No	Array of load line items
settings	object	No	{ mode, maxUses }
validDates	DateRange	No	{ begin, end } — bookable window
preferredDates	DateRange	No	{ begin, end } — preferred dates
description	string	No	Optional description
attributes	object	No	Key-value metadata
status	{ name }	No	Document status label
type	{ name }	No	Document type label

* At least one of occupant, offsite, or carrier must be provided.

Organisation reference

An organisation can be referenced by Mobiledock ID or by Core ID:

// By Mobiledock ID
{ "id": "990090c9-7506-487b-9872-c4e65557ae75" }

// By Core ID
{ "coreName": "SUPPLIER", "coreId": "0001" }

Load object

Property	Type	Required	Description
name	string	Yes	Load type name
quantity	number	Yes	Number of units
loadTag	string	No	Identifier (e.g. SKU)

Document modes

Mode	Description
Free	Booker can modify loads
Fixed	Booker cannot modify loads
Flexible	Booker can modify quantities but not load types

HTTP status codes

Upsert (PUT)

Code	Description
200	Document updated
201	Document created
400	Invalid payload — see response body

Fetch (GET)

Code	Description
200	Document returned

Delete (DELETE)

Code	Description
200	Document deleted

Batch delete (DELETE)

Code	Description
200	Delete job queued — the job record is returned
400	Empty document ID list, or documents are not enabled for the location
403	Token lacks the required permission
502	Job could not be queued — retry