Integration Setup

This guide walks you through setting up an API integration with Mobiledock, from choosing an environment to making your first request.

Before starting

Before commencing integration, please take the time to read through our Rate Limits & Fair Use Policy.

Setup steps

1. Select an environment and region

   Mobiledock has separate production regions and a staging environment. Each has its own dataset — no data is synced between them.

   See the Environments page for the full list of regions and URLs.

2. Select an organisation

   The organisation is a core concept in Mobiledock. Most API operations are in context of a particular organisation.

   To find your organisation ID:

   1. Visit the relevant Mobiledock environment and sign in.
   2. Navigate to the Organisations page.
   3. Click on the organisation you want to integrate with.
   4. Extract the organisation ID from the URL:

   https://my.mobiledock.com/organisations/990090c9-7506-487b-9872-c4e65557ae75
                                              └─── organisation ID ───┘

3. Create an API token

   Follow the Authentication guide to create a bearer token via the Integration Hub. You will need to select the correct permissions for your use case — see the Permissions Reference for the full list.

4. Set your token

   Export your token as an environment variable so you can reuse it:

   export MD_TOKEN="your-token-here"

5. Make your first request

   The simplest query you can make is to list bookings. This confirms your token is valid and has the correct permissions.

   curl

   curl -X POST https://my.mobiledock.com/api/v1/graphql \
     -H "Authorization: Bearer $MD_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "query": "{ bookings(count: 5) { results bookings { id direction status { name } requestedTime carrier { name } } } }"
     }'

   JavaScript

   const response = await fetch('https://my.mobiledock.com/api/v1/graphql', {
     method: 'POST',
     headers: {
       'Authorization': `Bearer ${process.env.MD_TOKEN}`,
       'Content-Type': 'application/json',
     },
     body: JSON.stringify({
       query: `{
         bookings(count: 5) {
           results
           bookings {
             id
             direction
             status { name }
             requestedTime
             carrier { name }
           }
         }
       }`,
     }),
   });
   
   const { data } = await response.json();
   console.log(`Found ${data.bookings.results} bookings`);

6. Check the response

   A successful response looks like:

   {
     "data": {
       "bookings": {
         "results": 3,
         "bookings": [
           {
             "id": "MDB-26-GS8Q-8Q30",
             "direction": "Inbound",
             "status": { "name": "Approved" },
             "requestedTime": "2026-03-28T19:00:00Z",
             "carrier": { "name": "Express Freight Co" }
           }
         ]
       }
     }
   }

Troubleshooting

Response	Cause	Fix
401 Unauthorized	Missing or invalid token	Check your Authorization header and token value
403 Forbidden	Token lacks required permission	Add the needed permission in the Integration Hub
Empty bookings array	No bookings match, or wrong org permissions	Ensure your token has BookingObservation permission

Next steps

• Querying Bookings — filter, paginate, and work with booking data
• Working with Documents — create and manage documents via REST
• Working with Passes — manage driver and vehicle passes
• API Reference — browse all available operations

If after reading this guide you have further questions, please contact us at assistance@mobiledock.com.