Working with Passes

This guide provides an overview of the Passes feature in Mobiledock and how to manage passes via the REST API.

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

Overview

Mobiledock’s Passes feature allows validation of entities authorised to be on-site, such as inducted drivers or authorised vehicles. It is built around two objects:

• Pass Type — a category of pass (e.g. “Driver Induction”, “Vehicle Registration”)
• Pass — an individual pass belonging to a pass type

Benefits

• Improved security and compliance — ensures only authorised drivers or vehicles can access the site
• Streamlined validation — integrating passes into your API workflows enables fast, scalable validation
• Flexible access management — passes support validity date ranges for time-limited access

Pass structure

A pass contains:

Property	Description
Pass ID	Unique identifier, inputted by the user
Attributes	Key-value pairs (e.g. driver name, vehicle registration)
Pass Type	The category this pass belongs to
Validity	Date range defining when the pass is valid
URL	Optional URL associated with the pass
Created/Modified Time	Timestamps for audit

A pass type contains:

Property	Description
ID	Unique identifier (UUID)
Name	Display name of the pass type
Pass Key	User-designated key used for REST API lookups
Passes	List of passes under this type

Requirements

• Your organisation has API access, location functionality, and passes functionality enabled
• You have created an API token with the PassManagement permission
• Pass types have been created through the website UI (pass types cannot be created via the API)

REST API endpoints

The root endpoint is /api/v2. All endpoints require the Authorization header.

Method	Endpoint	Description
GET	/api/v2/organisations/{orgId}/passes/{passKey}	Retrieve a pass type
GET	/api/v2/organisations/{orgId}/passes/{passKey}/{passId}	Retrieve a specific pass
PUT	/api/v2/organisations/{orgId}/passes/{passKey}/{passId}	Update a pass
DELETE	/api/v2/organisations/{orgId}/passes/{passKey}/{passId}	Delete a pass

Retrieve a pass type

curl

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

JavaScript

const orgId = '990090c9-7506-487b-9872-c4e65557ae75';
const response = await fetch(
  `https://my.mobiledock.com/api/v2/organisations/${orgId}/passes/driver`,
  { headers: { 'Authorization': 'Bearer YOUR_TOKEN' } }
);
const passType = await response.json();

Retrieve a specific pass

curl "https://my.mobiledock.com/api/v2/organisations/990090c9-7506-487b-9872-c4e65557ae75/passes/driver/mack-123" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example response:

{
  "id": "0400102390",
  "attributes": {
    "Driver Name": "Mack",
    "Rego": "XYZ 123"
  },
  "validity": {
    "begin": "2024-01-01T00:00Z",
    "end": "2024-12-01T00:00Z"
  },
  "url": "https://example.com/passes/0400102390",
  "createdAt": "2023-09-11T23:31:50.69",
  "modifiedAt": "2023-09-12T02:05:22.073"
}

Update a pass

The PUT payload accepts:

Field	Description
attributes	Key-value pairs for the pass holder (required)
url	URL for additional details (required)
validity	Object with begin and end dates

curl

curl -X PUT \
  "https://my.mobiledock.com/api/v2/organisations/990090c9-7506-487b-9872-c4e65557ae75/passes/driver/mack-123" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "attributes": { "driver name": "Mitchell" },
    "validity": { "begin": "2024-09-01T00:00:00.00Z" },
    "url": "https://example.com/passes/12345"
  }'

JavaScript

const orgId = '990090c9-7506-487b-9872-c4e65557ae75';
const response = await fetch(
  `https://my.mobiledock.com/api/v2/organisations/${orgId}/passes/driver/mack-123`,
  {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      attributes: { 'driver name': 'Mitchell' },
      validity: { begin: '2024-09-01T00:00:00.00Z' },
      url: 'https://example.com/passes/12345',
    }),
  }
);

Delete a pass

curl -X DELETE \
  "https://my.mobiledock.com/api/v2/organisations/990090c9-7506-487b-9872-c4e65557ae75/passes/driver/mack-123" \
  -H "Authorization: Bearer YOUR_TOKEN"

Next steps

• Passes REST API Reference — full endpoint specifications
• Permissions Reference — see the PassManagement permission

If you have additional questions, contact assistance@mobiledock.com.