Skip to main content

Integrating with Passes

This guide provides an overview of the Passes feature in Mobiledock and how to use the passed API.

Before proceeding, it is recommended that you follow the instructions in 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, and it is built around two objects:

  1. Passes
  2. Pass Types

Benefits of Passes​

  • Improved security and compliance: Ensures only authorised drivers or vehicles can access the site.
  • Streamlined validation process: The ability to integrate passes into your API workflows ensures fast and scalable validation for large organisations.
  • Partial validation: Supports defining pass validity over a range of dates, allowing for flexible access management.

Included in a Pass​

A Pass contains the following details:

  • Pass ID: A unique identifier for the pass, inputted by the user.
  • Attributes: Fields associated with the pass, such as driver name or vehicle registration.
  • Pass Type: The pass type associated with the pass.
  • Pass Validity: A date range defining when the pass is valid.
  • Pass URL: A URL associated with the pass.
  • Created Time Timestamp for when the pass was created.
  • Modified Time Timestamp for when the pass was last modified.

A Pass Type contains the following details:

  • ID: A unique identifier for the pass type.
  • Pass Name: The name of the pass type.
  • Passes: A list of passes associated with the pass type.
  • Pass Key: A unique identifier, designated by the user and used for lookups with the REST API.

Requirements​

To integrate the Passes feature into Mobiledock, the following prerequisites must be met:

  • Your organisation has API access, location functionality, and passes functionality enabled by your account manager.
  • You have created an API token with the permission of PassManagement.
  • You have a working Mobiledock configuration, with pass types created through the website's UI. Note that pass types cannot be created via the API.

REST API for Passes​

Mobiledock’s Passes feature can be accessed via its REST API for managing passes. The root endpoint for the API is /api/v2. Below, we outline each of the available endpoints for interacting with passes.

Note: Some operations related to passes can only be performed using the GraphQL API, such as listing passes of a particular pass type or creating new passes. This guide focuses on the REST API.

Available Endpoints​

HTTP MethodEndpointDescription
GET/api/v2/organisations/:organisation_id/passes/:pass_keyRetrieves the pass type associated with a pass key
GET/api/v2/organisations/:organisation_id/passes/:pass_key/:pass_idRetrieve a specific pass by its ID
PUT/api/v2/organisations/:organisation_id/passes/:pass_key/:pass_idUpdate an existing pass
DELETE/api/v2/organisations/:organisation_id/passes/:pass_key/:pass_idDelete a specific pass

Example Payload​

An example of the response payload for retrieving pass details via the GET requests:

{
  "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"
}

Retrieve Pass Types​

GET /api/v2/organisations/:organisation_id/passes/:pass_key​

This endpoint retrieves the pass type associated with the provided pass_key.

Example Request:​

GET https://my.mobiledock.com/api/v2/organisations/990090c9-7506-487b-9872-c4e65557ae75/passes/driver

This request retrieves the pass types related to the driver pass key for organisation 990090c9-7506-487b-9872-c4e65557ae75.

Retrieve Pass Details​

GET /api/v2/organisations/:organisation_id/passes/:pass_key/:pass_id​

This endpoint retrieves details for a specific pass identified by its pass_id.

Example Request:​

GET https://my.mobiledock.com/api/v2/organisations/990090c9-7506-487b-9872-c4e65557ae75/passes/driver/mack-123

This request retrieves the pass with ID mack-123 that belongs to the driver pass type.

Update Pass Details​

PUT /api/v2/organisations/:organisation_id/passes/:pass_key/:pass_id​

This endpoint is used to update the details of an existing pass for a given pass_key and pass_id.

FieldDescription
attributesKey-value pairs containing relevant information about the pass holder (e.g., driver name, vehicle registration) (required).
urlA URL for additional details or documentation related to the pass (required).
validDatesDefines the validity period of the pass. It includes a begin and end date.

Example Request:​

PUT https://my.mobiledock.com/api/v2/organisations/990090c9-7506-487b-9872-c4e65557ae75/passes/driver/mack-123

With the following payload in the body of the request:

{
  "attributes": {
    "driver name": "Mitchell"
  },
  "validity": {
    "begin": "2024-09-01T00:00:00.00Z"
  },
  "url": "https://example.com/passes/12345"
}

In this example, we update the attributes of the pass with ID mack-123, changing the driver name attribute, the URL and the validity period.

Delete a Pass​

DELETE /api/v2/organisations/:organisation_id/passes/:pass_key/:pass_id​

This endpoint deletes a specific pass based on its pass_key and pass_id.

Example Request:​

DELETE https://my.mobiledock.com/api/v2/organisations/990090c9-7506-487b-9872-c4e65557ae75/passes/driver/mack-123

This request deletes the pass with ID mack-123 that belongs to the driver pass type.

Next Steps​

For more detailed information on the API and payloads, please refer to the Passes API Specification.

If you require assistance or have additional questions about integrating Passes into your solution, please contact Mobiledock support at assistance@mobiledock.com.