There are many situations where your internal operational systems (gate control system, front automated kiosks), want to verify with Inbound Connect whether a booking has been made for the truck/driver that has just arrived at your site.
This feature allows you to query the currently active bookings by a particular field value (typically vehicle registration number or driver details) to determine if there are active bookings for that arrival and whether those bookings are on time, early, late and able to be processed.
The integration flow is as follows:
- Generate an API key for a user (or create a generic integration user first) within your facility account.
- Query the API endpoint passing in the field name and value you are looking for.
- The system will return any active bookings for those details and provide you details of if they are early/late/on time and but how much.
Endpoint
The get available bookings API URL will be provided by your Inbound Connect account or support team member. Please contact them to get the URL.
Security
To authenticate to the Inbound Connect API, you first need to generate an API token for a user with permissions to edit bookings. You can either create a generic user with just this permission, or use an existing user.
- Once logged in as the user in question.
- Go to the My Settings menu in the top right of the screen.
- Select the API Keys tab and click New API Key.
- Copy down the API key as once the window is closed you won’t be able to retrieve it again and you will be required to generate a new key.
- To all HTTP requests to the Inbound Connect endpoint ensure you have the following HTTP Header added.
- Inbound-API-Key: <emailaddress>:<apikey>
- Where email address is the email address of the user within your facility account
- And apikey is the value copied from step 4 above.
This particular Inbound Connect endpoint requires a HTTP GET request and accepts two query string parameters to the API endpoint.
Note all query string parameters should be URL encoded (especially when there are spaces in the field name or value parameters).
Query String Parameters
| Field | Description | Comments |
|---|---|---|
| field | The name of the field you wish to query against. Ask Inbound Support or your Inbound Connect contact person for the correct field value you should be using for your particular use case. | Provided by Inbound |
| value | The value against which you wish to query | Value entered into your kiosk system or provided by your gate automation solution (ANPR, OCR etc) |
Example
GET https://url.provided.by.inbound/apiendpoint?field=Vehicle%20Rego&value=ABC123
This particular Inbound Connect endpoint responds with a JSON response.
Field Descriptions
| Field | Description | Format/Comments |
|---|---|---|
| error | The error object. Will have details if success = False | Object |
| error.code | Error code for this particular error message | Number |
| error.details | Most often null but may have additional details to your particular message | String |
| error.message | The error message describing what is wrong with your request | String |
| success | Indicates whether the call to the API was successful or not. | Boolean: True/False |
| result | Array of objects representing the response to your successful API call | JSON array |
| result.bookingNumber | The booking number | String |
| result.facility | Name of the facility | String |
| result.service | Name of the service | String |
| result.bookingDate | Date for the booking | String (yyyy-mm-dd) |
| result.startTimeWindow | Start time of the booking | String (hh:mm) |
| result.endTimeWindow | End time of the booking | String (hh:mm) |
| result.secondaryCapacityFieldName | Name of the secondary capacity field | String (optional) |
| result.secondaryCapacityQuantity | Quantity of the secondary capacity | Number (optional) |
| result.transporter | Name of the transport company | String |
| result.guestName | If this booking is a guest/one-off booking the name of the guest person | String |
| result.guestEmail | If this booking is a guest/one-off booking the email of the guest person | String |
| result.preProcessed | Indicator as to whether this booking is pre-processed already or not | Boolean: True/False |
| result.status | Status of the booking (OnTime, Early, Late) | String |
| result.statusMinutes | If not on time the number of minutes that the arrival is early or late (based on the time of query) | Number |
| result.earlyThresholdMin | For this particular service what is the number of minutes before the start time window that is considered early | Number |
| result.lateThresholdMin | If not on time the number of minutes that the arrival is early or late (based on the time of query) | Number |
| result.fields | An array of field values for each of the fields on this booking | JSON Array |
| result.fields.field | Name of the field | String |
| result.fields.value | Value for that particular field on this booking | String |
| result.attachments | An array of attachments for this booking | JSON Array |
| result.attachments.fileName | Filename of the attachment | String |
| result.attachments.attachmentType | The type of attachment | String |
| result.attachments.url | A time limited secure URL allowing you to download this file if required | String |
Example Success
{
"result": [
{
"bookingNumber": "INBFAC2404191",
"facility": "Inbound Facility",
"service": "FAK Import Pickup",
"bookingDate": "2024-04-19",
"startTimeWindow": "23:00",
"endTimeWindow": "23:59",
"secondaryCapacityFieldName": "Pallets",
"secondaryCapacityQuantity": 5,
"transporter": "Inbound Transporter",
"guestName": null,
"guestEmail": null,
"preProcessed": false,
"status": "Early",
"statusMinutes": 918,
"earlyThresholdMin": 57,
"lateThresholdMin": 30,
"fields": [
{
"field": "Vehicle Rego",
"value": "ABC123"
},
{
"field": "Container No.",
"value": "CONT123"
},
{
"field": "Container Size",
"value": ""
},
{
"field": "House BL",
"value": "HBL123"
},
{
"field": "Special Instructions",
"value": ""
}
],
"attachments": [
{
"fileName": "attachmentname.pdf",
"attachmentType": "Delivery order",
"url": "https://timelimited.url.to.file"
}
]
}
],
"targetUrl": null,
"success": true,
"error": null,
"unAuthorizedRequest": false,
"__abp": true
}
Example Error
{
"result": null,
"targetUrl": null,
"success": false,
"error": {
"code": 0,
"message": "Unable to validate API Key Headers",
"details": null,
"validationErrors": null
},
"unAuthorizedRequest": false,
"__abp": true
}
[jsoncontentimporter url=”https://api.inboundconnect.com/api/services/app/Public/GetDraftBookingReferenceDetails” basenode=result]
Each facility has the ability to define their own attachment types. Please ensure you only send in codes that match the facility you are targeting. If the facility is not listed then use the base attachment types.
[/jsoncontentimporter]| Facility Name | ||||
|---|---|---|---|---|
{attachmentTypesByFacility.facilityName}
| {/subloop-array:attachmentTypesByFacility}