Working with Documents

This guide covers how documents are used in Mobiledock and the process required to integrate with them via the REST API.

Before proceeding, it is recommended that you follow the Integration Setup guide.

Overview

In Mobiledock, a document is a record of a pre-determined reason to visit a Mobiledock-controlled site. Most commonly, documents model a Purchase Order (PO), an Advanced Shipping Notice (ASN), or a Work Order.

Benefits

• Ensures individuals creating a booking have a valid reason to be on site
• Less data is required from the booker — much of it can be pre-filled
• Earlier visibility of specific orders for better resource planning

Requirements

• Your organisation has API access, location functionality, and document functionality enabled
• You have created an API token with Document Observation and Document Management permissions
• You have a working Mobiledock configuration with connections to suppliers, receivers, and carriers

Anatomy of a document

ID

The unique identifier of the document, entered by users when creating a booking at your site.

Direction

Either Inbound or Outbound, depending on the nature of the visit.

Occupant, offsite, and carrier

The occupant is the organisation that occupies the location. The offsite is the remote organisation. The carrier handles transport.

Note

For inbound documents, the offsite is the sender and the occupant is the receiver. For outbound documents, the occupant is the sender and the offsite is the receiver.

When using the REST API, reference organisations by their Core ID — a mapping between your system’s identifiers and Mobiledock’s internal organisations. At least one of occupant, offsite, or carrier must be defined on a document.

Loads

Loads model the units related to a document. Each line contains:

Property	Description
Load Type	The type of load, referenced by name or ID
Quantity	The number of units for this line
Load Tag (optional)	An identifier for this line (e.g. an SKU)

Document mode

Document mode determines how a document can be booked against:

Mode	Description
Free	The load may be modified by the booker
Fixed	The load cannot be modified by the booker
Flexible	Load quantities may be modified, but load types cannot

Other properties

Property	Description
Valid Dates	Time window when bookings can be scheduled (both optional)
Preferred Dates	Preferred delivery dates shown to users (both optional)
Max Uses	Maximum number of bookings against this document
Description	Optional text displayed to the user when booking
Attributes	Optional key-value store for integration metadata
Status	Optional state indicator (e.g. “High Priority”)
Type	Optional classification (e.g. “PO”, “ASN”)

Creating a document

Example payload

In this example, we create a document for organisation 990090c9-7506-487b-9872-c4e65557ae75:

{
  "id": "PO-2000",
  "direction": "Inbound",
  "occupant": {
    "id": "990090c9-7506-487b-9872-c4e65557ae75"
  },
  "offsite": {
    "coreName": "SUPPLIER",
    "coreId": "0001"
  },
  "loads": [
    { "name": "Cartons", "quantity": 500, "loadTag": "SKU-199" },
    { "name": "Cartons", "quantity": 1000, "loadTag": "SKU-094" }
  ],
  "settings": {
    "mode": "Fixed",
    "maxUses": 1
  },
  "validDates": {
    "begin": "2024-09-01T21:00:00Z",
    "end": "2024-10-01T21:00:00Z"
  },
  "preferredDates": {
    "end": "2024-09-15T21:00:00Z"
  },
  "attributes": {
    "PRIORITY": "1",
    "SUPPLIER_CATEGORY": "03"
  },
  "status": { "name": "High Priority" },
  "type": { "name": "PO" }
}

Submitting a document

The recommended method is the upsert operation — it updates an existing document if it exists, or creates a new one.

curl

curl -X PUT \
  "https://my.mobiledock.com/api/v2/organisations/990090c9-7506-487b-9872-c4e65557ae75/documents/PO-2000?upsert=true" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d @document.json

JavaScript

const orgId = '990090c9-7506-487b-9872-c4e65557ae75';
const docId = 'PO-2000';

const response = await fetch(
  `https://my.mobiledock.com/api/v2/organisations/${orgId}/documents/${docId}?upsert=true`,
  {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(documentPayload),
  }
);

Tip

If submitting many documents at once, use the more efficient Batch Document Job endpoint.

Handling unmatched Core IDs

By default, the API rejects documents when the Core ID and Core Name do not match an existing connection. To automatically create a new organisation when details can’t be matched, add enableBaseOrgs=true to the query string:

/api/v2/organisations/{orgId}/documents/{docId}?upsert=true&enableBaseOrgs=true

HTTP status codes

Status Code	Description
200	Document updated successfully
201	Document created successfully
400	Payload issue — details in response body

Document batch jobs

Batch jobs are an efficient way to submit large numbers of documents at once. A single payload containing many documents is processed asynchronously.

Submitting a batch

Send a JSON array of documents as an HTTP POST to:

/api/v2/organisations/{orgId}/document-jobs/

All documents use the upsert method. Add enableBaseOrgs=true and selfCoreId=DC as needed:

curl -X POST \
  "https://my.mobiledock.com/api/v2/organisations/990090c9-7506-487b-9872-c4e65557ae75/document-jobs?enableBaseOrgs=true&selfCoreId=DC" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{ ... }, { ... }]'

Other batch endpoints

Method	Endpoint	Description
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 an in-progress batch

Fetching a document

Send an HTTP GET request to the document resource:

curl "https://my.mobiledock.com/api/v2/organisations/990090c9-7506-487b-9872-c4e65557ae75/documents/PO-2000" \
  -H "Authorization: Bearer YOUR_TOKEN"

The response includes resolved organisation details including addresses and connection attributes.

Deleting a document

Deleting a document prevents additional bookings from being created against it. Existing bookings retain their document reference.

curl -X DELETE \
  "https://my.mobiledock.com/api/v2/organisations/990090c9-7506-487b-9872-c4e65557ae75/documents/PO-2000" \
  -H "Authorization: Bearer YOUR_TOKEN"

Next steps

• Documents REST API Reference — full endpoint specifications
• Querying Bookings — work with bookings that reference documents

If you have further questions, contact us at assistance@mobiledock.com.