API Access Token

v1_booking API

/**
 * REST API end-points for interacting with the 'booking', and related, resources.
 * 
 */
Sign in
Available APIs
v1_active_people v1_asignit v1_asset v1_booking v1_booking_client_contact v1_client v1_client_contact v1_depot v1_document_type v1_driver_licence_type v1_equipment v1_files v1_form v1_invoice v1_item_classification v1_lookup v1_person v1_project v1_resource v1_sage_50 v1_skill v1_tag v1_upload v1_vehicle v1_works_docket
Methods
  • booking_equipment GET
  • booking_person GET PUT DELETE
  • booking_requirement GET PUT DELETE
  • booking_status GET
  • booking_story GET POST PUT DELETE
  • booking_vehicle GET PUT
  • booking GET POST
    • Help
    Definitions
    T-2.931.3
    Release Notes

    API Release Notes

    Close

    Version T-2.931.3, released on 19/03/2025

    • Third party API
      • Improvement: State timezone information (state_id and state_timezone) fields have been added to `v1_booking/booking` and `v1_depot/depot` GET end-points.
      • Improvement: `v1_lookup/state` end-point has been added to look up information about about state records.

    Version T-2.911.1, released on 06/01/2025

    • Third party API
      • New Feature: Invoice Item: Invoice items have been added to the third party api within the V1_invoice api. Note: a date range is required

    Version T-2.906.1, released on 27/11/2024

    • Third party API
      • New Feature: Added PUT and POST end-points for projects. Use of these end-points is controlled with the 'Project Write Access' permission requiring a Traffio team member to enable.

    Version T-2.900.1, released on 15/10/2024

    • Third party API
      • Asset: vehicle_id added to output of asset GET
      • Asset: vehicle_id and person_id added as filters to asset GET

    Version T-2.894.1, released on 25/08/2024

    • Third party API
      • Improvement: Added end-points 'person_file_download' and 'person_skill_file_download' for downloading protected files for people and for people's skills.

    Version T-2.891.2, released on 19/09/2024

    • Third party API
      • Improvement: created_by data has been added to the output of the v1_vehicle_api vehicle end point.

    Version T-2.883.1, released on 06/08/2024

    • Third party API changes: vehicle_engine_number
      • vehicle_engine_number has been added to the output of the v1_vehicle_api vehicle end point.

    Version T-2.881.2, released on 05/08/2024

    • Get bookings by Job number is no longer a unique record
      • Job numbers can now be duplicated. This is now the case for companies that have merged their data from several pre existing Traffio Customers.
      • Get booking by job_number will now return an array of results not a single result.

    Version T-2.876.1, released on 27/07/2024

    • Third party API changes: Item_classification
      • Added a GET API endpoint 'item_classification' to show the item_classifications that are used by booking requirements.
      • Added a GET API endpoint 'item_classification_resource' to show the quantity of resources used by each item_classification.

    Version T-2.860.1, released on 06/06/2024

    • Third party API changes
      • Added a GET api endpoint 'active_people_get' to retrieve active and working people and their hours worked.

    Version T-2.851.1, released on 3/05/2024

    • Third Party API changes
      • Ordering of results has been removed from the booking_person and works_docket_person endpoints.
      • We have optimised the performance of a number of endpoints that had started to slow down.

    Version T-2.850.3, released on 2/05/2024

    • Third Party API changes
      • v1_booking: Added an endpoint for updating booking requirements
      • v1_booking: Added an endpoint for deleting booking requirements

    Version T-2.844.1, released on 15/04/2024

    • Third Party API changes
      • v1_booking: Added an endpoint for posting bookings
      • v1_booking: Added an endpoint for retrieving booking requirements
      • v1_project: Added fields required_skill_ids and required_vehicle_induction_ids when retrieving projects
      • v1_vehicle: Added an endpoint for retrieving vehicle availability
      • v1_person: Added an endpoint for retrieving a person's blocklist

    Version T-2.840.1, released on 02/04/2024

    • Third Party API: Added fields for GET Works_docket_person
      • driver_for_vehicle_id
      • passenger_for_vehicle_id
      • equipment_ids

    Version T-2.816.5, released on 06/12/2023

    • Third Party API: Added fields for GET Person
      • person_start_date
      • person_probation_date
      • person_active_date
      • person_finish_up_date
      • driver_licence_type_name
      • person_driver_licence_number
      • person_driver_licence_date_granted
      • person_driver_licence_expiry_date

    Version T-2.811.3, released on 31/10/2023

    • Third Party API: Depot
      • 'customer_name' has been added to the output of GET depot

    Version T-2.799.1, released on 01/08/2023

    • Third party API changes
      • Added third party API end-point for availability (person leave). The end point can be found in the v1_person api.
      • v1_person:person endpoint person_lng, person_lat
      • v1_booking:booking has new fields added: booking_lng, booking_lat, booking_touches_shifts
      • booking_touches_shifts can be used to match available periods for weekday day/night shifts using a bitwise comparison. The maping can be found in the person availability api

    Version T-2.793.1, released on 15/08/2023

    • Third Party API
      • An API for Assets has been added under V1_asset.

    Version T-2.792.1, released on 11/08/2023

    • Third Party API
      • Booking write access has been added to the third party V1_booking API
      • Currently limited to writing booking person records. Will be expanded to cover equipment, and vehicles shortly.
      • booking_person_put, booking_person_delete added
      • is_non_billable added to the booking person api
      • booking_write_access added to the third party interface. this must be selected for the third party token to be able to write to bookings

    Version T-2.717.1, released on 23/11/2022

    • Third party API end-points
      • Added third party API end-points for retrieving booking vehicles, booking equipment, forms and form submissions. Requires corresponding third party permissions to be switched on - see 'Integrations' > Select a 'Personal' third party.

    Version T-2.693.2, released on 14/9/2022

    • Third party works dockets API
      • Added third party API end-points for retrieving works docket records. Requires the third party permission 'Works Docket Read Access' to be switched on - see 'Integrations' > Select a 'Personal' third party > 'Works docket read access' field.

    Version T-2.692.2, released on 12/9/2022

    • Third party person API: update person
      • A person can now be updated through the third party API using eth PUT method if the token has write permission
      • Not all fields can be updated
      • This will allow Staffd to update existing users with their new release next week

    Version T-2.689.2, released on 5/9/2022

    • Third party person API: Second Emergency Contact
      • A second emergency contact has been added.
      • Added to input of POST person: person_emergency_contact_name2, person_emergency_contact_phone2, person_emergency_contact_relationship2
      • Added to output of GET person: person_emergency_contact_name, person_emergency_contact_phone, person_emergency_contact_relationship, person_emergency_contact_name2, person_emergency_contact_phone2, person_emergency_contact_relationship2

    Version T-2.655.1, released on 6/5/2022

    • Third party booking API
      • Added to output of get booking: client_order_number
      • Added to output of get booking: client_billing_code

    Version T-2.645.4, released on 21/4/2022

    • Staffd integration : bugfix
      • Newly uploaded employees from Staffd would always default to a "candidate" if an avatar image was also uploaded. Uploaded employees will now have the status that is specified
      • Social inclusions, Gender, and Pronouns are now included in Traffio's third party API. It is expected that Staffd will soon include these fields in uploads to Traffio

    Version T-2.542.1, released on 24/08/2021

    • Issuing new access tokens for third parties will now revoke previous access tokens.
    • Made links which are issued to third parties for generating access tokens, expire after 30 days un-viewed and 24 hours once viewed.

    Version T-2.535.1, released on 17/08/2021

    • Traffio support tools
      • This is for the Traffio Support Team
      • Conversations now have dynamic links to the customer, the contact and their conversations
      • Report links have been added, as well as a new teleportation tool
      • fixed bug with creating new methods, and methods nwo have coloured tags

    Version T-2.534.1, released on 16/08/2021

    • Internal 3rd party integrations
      • You can setup access to your Traffio data using the API by creating your own 'Third Party' integration. See the 'Integrations' main menu (moved from 'My Company').
      • Your integrations are restricted to reading your data while Traffio approved integrations will have limited ability to read and write to your data depending on their requirements.
      • You have full control of which integrations can access your data.

    Version T-2.490.1, released on 14/05/2021

    • Added ability to upload a person's profile image, documents and skill-documents via the third party API.

    Version T-2.360.1, released on 11/05/2020

    • Third Party API
      • Third party API end points have been added for vehicles and equipment
      • API has also been opened up to allow third parties to update ODO readings and schedules of service
      • Vehicle issues may also be reported and maintained through the third party api

    Version T-2.330.1, released on 6/2/2020

    • Third Party API
      • Released today is the Traffio third party API for external software to hook into. You can allow external software vendors to make use of this API by generating a token for them through My Company > Integrations.
      • The first third party software available through the platform is Actiond. Link: https://Actiond.io
      • Actiond provides surveys which gauge client and employee satisfaction
    Booking Equipment HTTP GET request

    Returns information about the 'booking_equipment' resource filterable by the fields described below. This resource describes vehicles that are assigned to bookings.
    Requires 'Booking Read Access' and 'Equipment Read Access' to be enabled in the 'Permissions' section of your Third Party Integration
    @return array of resources. Returns a single record if the booking_id and equipment_id is provided.
    Field Description
    Comma Separated list of columns to restrict results to. Order is kept. If field does not exist then column will be included, but a blank result will be returned
    eg: "name,description,created_by"

    Currently only enabled for GET requests using formats of HTML, TSV, CSV
    Comma Separated list of columns to exclude from results.
    Currently only enabled for GET requests using formats of HTML, TSV, CSV Note: Exclude field will be ignored if fields are supplied.
      
    Booking Person HTTP DELETE request

    Deletes the specified booking person.
    Requires 'Booking Write Access' to be enabled in the 'Permissions' section of your Third Party Integration
    UNKNOWN
    Field Description
    (required)
    (required)
      
    Booking Person HTTP GET request

    Returns information about the 'booking_person' resource filterable by the fields described below. This resource provides additional
    information about a person in the context of a booking. Results are ordered by booking_start_time and limited to 2000.
    Requires 'Booking Read Access' and 'Person Read Access' to be enabled in the 'Permissions' section of your Third Party Integration
    @return array of resources. Returns a single record if the person_id and booking_id values provided.
    Field Description
    Comma Separated list of columns to restrict results to. Order is kept. If field does not exist then column will be included, but a blank result will be returned
    eg: "name,description,created_by"

    Currently only enabled for GET requests using formats of HTML, TSV, CSV
    Comma Separated list of columns to exclude from results.
    Currently only enabled for GET requests using formats of HTML, TSV, CSV Note: Exclude field will be ignored if fields are supplied.
    The unique ID of the booking that the resource belongs to. If both person_id and booking_id are provided, a single record is returned.
    A datetime indicating the lower range of the starting datetime of a resource. Returns all resources which have a starting time greater than the datetime provided.
    A datetime indicating the upper range of the starting datetime of a resource. Returns all resources which have a starting time less than the datetime provided.
    A unique ID of a depot to which the booking belongs.
    Flag indicating if the resource is deleted or not. 0 = not deleted, 1 = deleted.
    A datetime of which the resource was last modified in the format of YYYY-MM-DD HH:mm:ss. Returns records with a last_modified datetime value greater that the datetime provided.
    The unique ID of the person that the resource belongs to. If both person_id and booking_id are provided, a single record is returned.
      
    Booking Person HTTP PUT request

    Updates an existing booking person, and if successful returns information about the updated booking person.
    Requires 'Booking Write Access' to be enabled in the 'Permissions' section of your Third Party Integration
    @return ARRAY
    Field Description
    (required)
    (YYYY-MM-DD HH:mm:ss) used if the person is to finish at a time different form the start time of the booking
    (YYYY-MM-DD HH:mm:ss) used if the person is to start at a time different form the start time of the booking
    [1 or 0]
    (required) [1 or 0] used if the person is to drive the vehicle. (otherwise they will be a passenger)
    [1 or 0] if 1 then this will not be included in invoicing
    (required) [1 or 0] (straight to site) if 1 then the person is to meet at site, rather than the depot. The default setting for this is a configuration setting. the default configuration setting will be used if this value is not supplied
    [1 or 0] Note: only one person can be team leader
    (required)
    this determines the specialisation that person will perform on site
    used if the person is a passenger or driver
      

    Removes an existing booking requirement
    Requires 'Booking Write Access' to be enabled in the 'Permissions' section of your Third Party Integration
    @return ARRAY
    Field Description
    (required)
    (required)
      
    Booking Requirement HTTP GET request

    Returns information about the 'booking_requirements' resource filterable by the fields described below.
    Requires 'Booking Read Access' to be enabled in the 'Permissions' section of your Third Party Integration

    The requirements of a booking are listed as quantities of item classification.
    Each item classification is a group of resources. eg:a '3 TC crew' which would include three traffic controllers and one vehicle
    so 2 x '3 TC crew' would be 6 traffic controllers and 2 vehicles
    sample output
    [{
    "booking_id": "1223",
    "item_classification_id": "1",
    "booking_requirement_quantity": "1", (quantity of this item classification)
    "item_classification_name": "Traffic Controller",
    "item_classification_code": null,
    "added_to_agreement": "1", (if the item is on the billing agreement, then this value will be 1)
    "contains_docs_or_stock": "0", (items that are not vehicles, equipment or people)
    "contains_allocatables": "1",
    "number_of_people": "1", ( number of people: this field may be removed in the future as it is a legacy field)
    "number_of_vehicles": null, ( number of vehicles: this field may be removed in the future as it is a legacy field)
    "number_of_equipment": null, ( number of equipment: (arrow boards, vms boards etc) this field may be removed in the future as it is a legacy field)
    "booking_start_time": "2019-05-13 05:00:00",
    "approx_booking_end_time": "2019-05-13 13:00:00",
    "is_deleted": "0",
    "created_on": "2017-04-07 00:55:06",
    "created_by": "25",
    "last_modified": "2017-04-07 00:55:06",
    "modified_by": "25",
    "max_last_modified": "2023-11-13 04:42:26.7571"
    }]
    @return Array of booking requirements.
    Field Description
    Comma Separated list of columns to restrict results to. Order is kept. If field does not exist then column will be included, but a blank result will be returned
    eg: "name,description,created_by"

    Currently only enabled for GET requests using formats of HTML, TSV, CSV
    Comma Separated list of columns to exclude from results.
    Currently only enabled for GET requests using formats of HTML, TSV, CSV Note: Exclude field will be ignored if fields are supplied.
    will return any booking that starts after or overlaps this time
    limits to any booking that starts before or overlaps this time
    (1 or 0)
    comma separated of integers eg: '1,3,56'
    (YYYY-MM-DD HH:mm:ss), if supplied, only records modified more recent than this datetime will be returned
      
    Booking Requirement HTTP PUT request

    Updates an existing booking requirement, and if successful returns information about the updated booking person.
    Requires 'Booking Write Access' to be enabled in the 'Permissions' section of your Third Party Integration
    @return ARRAY
    Field Description
    (required)
    (1 or 0)
    (required)
      
    Booking Status HTTP GET request

    Returns information about the 'booking_status' resource (referred to as 'resource' below) filterable by the fields described below.
    The booking_status resource is mostly static and cannot be modified by the end user via the interface.
    Requires 'Booking Read Access' to be enabled in the 'Permissions' section of your Third Party Integration
    Resource response fields:
    - 'booking_status_id' (primary key, number):
    - 'booking_status_name' (string): The human readable name of the resource.
    - 'booking_status_description' (string): The human readable description of the resource.
    @return array of resources. Returns a single record if the booking_status_id is provided.
    Field Description
    Comma Separated list of columns to restrict results to. Order is kept. If field does not exist then column will be included, but a blank result will be returned
    eg: "name,description,created_by"

    Currently only enabled for GET requests using formats of HTML, TSV, CSV
    Comma Separated list of columns to exclude from results.
    Currently only enabled for GET requests using formats of HTML, TSV, CSV Note: Exclude field will be ignored if fields are supplied.
    The unique ID of the desired resource. Returns a single record if it exists. Other filters do not apply.
      
    DELETE booking_story
    /api_third_partyv1_booking/booking_story
    Deletes an existing booking_story record.
    Requires 'Booking Story Write Access' to be enabled in the 'Permissions' section of your Third Party Integration
    @return ARRAY
    Field Description
    The unique ID of the booking the booking_story record is linked to. Required, along with story_key, if booking_story_id is not provided.
    The unique ID of the booking story record to be deleted. Required if booking_id and story_key are not provided.
    The unique Story key of the booking_story record to be deleted. Required, along with booking_id, if booking_story_id is not provided.
      
    GET booking_story
    /api_third_partyv1_booking/booking_story
    Retrieves booking_story records based on the provided filters.
    Requires 'Booking Story Read Access' to be enabled in the 'Permissions' section of your Third Party Integration
    @return array of resources. Returns a single record if the booking_story_id is provided.
    Field Description
    Comma Separated list of columns to restrict results to. Order is kept. If field does not exist then column will be included, but a blank result will be returned
    eg: "name,description,created_by"

    Currently only enabled for GET requests using formats of HTML, TSV, CSV
    Comma Separated list of columns to exclude from results.
    Currently only enabled for GET requests using formats of HTML, TSV, CSV Note: Exclude field will be ignored if fields are supplied.
    The unique ID booking record that this story belongs to. Part of the unique key in combination with story_key.
    The unique ID of the desired resource. Returns a single record if it exists. Other filters do not apply.
    The unique ID of the client that this story belongs to.
    The lower limit of a date range that the linked booking touches. Refer to
    The upper limit of a date range that the linked booking touches. Refer to
    Flag indicating if the record is deleted or not. 0 = not deleted, 1 = deleted.
    The unique ID of the project that this story belongs to.
    The unique Story key provided by SiteStory. Part of the unique key in combination with booking_id.
      
    POST booking_story
    /api_third_partyv1_booking/booking_story
    Creates a new booking_story record, and if successful returns information about the created booking_story.
    Requires 'Booking Story Write Access' to be enabled in the 'Permissions' section of your Third Party Integration
    @return ARRAY
    Field Description
    Required. The unique ID of the booking record that this record will be associated with.
    The name of the author of the Story. Max length 255 characters.
    Length of the video in seconds.
    Required. The end date-time of the Story in UTC. Format: YYYY-MM-DD HH:mm:ss
    Full url to the private video. Max length 255 characters.
    latitude of address location up to 8 decimal places.
    longitude of address location up to 8 decimal places.
    Full url to the publicly-shareable video. Max length 255 characters.
    Required. The start date-time of the Story in UTC. Format: YYYY-MM-DD HH:mm:ss
    Full url to a thumbnail preview image. Max length 255 characters.
    Required. The unique Story key provided by SiteStory.
      
    PUT booking_story
    /api_third_partyv1_booking/booking_story
    Updates an existing booking_story record, and if successful returns information about the updated booking_story.
    Requires 'Booking Story Write Access' to be enabled in the 'Permissions' section of your Third Party Integration
    @return ARRAY Returns the updated booking_story record.
    Field Description
    The unique ID of the booking the story is linked to. Required, along with story_key, if booking_story_id is not provided.
    The name of the Story's author. Max length 255 characters.
    Length of the video in seconds.
    End date-time of the Story in UTC. Format: YYYY-MM-DD HH:mm:ss
    The unique ID of the booking story record to be updated. Required if booking_id
    The full url to the private video. Max length 255 characters.
    latitude of address location. Up to 8 decimal places.
    longitude of address location. Up to 8 decimal places.
    The full url to the publicly-shareable video. Max length 255 characters.
    Start date-time of the Story in UTC. Format: YYYY-MM-DD HH:mm:ss
    The full url to a thumbnail preview image. Max length 255 characters.
    (1 or 0)
    The unique Story key of the booking_story record to be updated. Required, along with booking_id, if booking_story_id is not provided.
      
    Booking Vehicle HTTP GET request

    Returns information about the 'booking_vehicle' resource filterable by the fields described below. This resource describes vehicles that are assigned to bookings.
    Requires 'Booking Read Access' and 'Vehicle Read Access' to be enabled in the 'Permissions' section of your Third Party Integration
    @return array of resources. Returns a single record if the booking_id and vehicle_id is provided.
    Field Description
    Comma Separated list of columns to restrict results to. Order is kept. If field does not exist then column will be included, but a blank result will be returned
    eg: "name,description,created_by"

    Currently only enabled for GET requests using formats of HTML, TSV, CSV
    Comma Separated list of columns to exclude from results.
    Currently only enabled for GET requests using formats of HTML, TSV, CSV Note: Exclude field will be ignored if fields are supplied.
      
    Booking Vehicle HTTP PUT request

    Updates an existing booking vehicle, and if successful returns information about the updated booking vehicle.
    If equipment ID is set, then this equipment will be removed from any other vehicle that has it in this booking.
    Requires 'Booking Write Access' to be enabled in the 'Permissions' section of your Third Party Integration
    @return ARRAY
    Field Description
    (required)
    (1 or 0)
    (required)
      
    Booking HTTP GET request

    Returns information about the 'booking' resource filterable by the fields described below. Results are ordered by booking_start_time and limited to 2000.
    Requires 'Booking Read Access' to be enabled in the 'Permissions' section of your Third Party Integration
    @return array of resources. Returns a single record if the booking_id or job_number is provided.
    Field Description
    Comma Separated list of columns to restrict results to. Order is kept. If field does not exist then column will be included, but a blank result will be returned
    eg: "name,description,created_by"

    Currently only enabled for GET requests using formats of HTML, TSV, CSV
    Comma Separated list of columns to exclude from results.
    Currently only enabled for GET requests using formats of HTML, TSV, CSV Note: Exclude field will be ignored if fields are supplied.
    The unique ID of the desired resource. Returns a single record if it exists. Other filters do not apply.
    The unique ID of the status that the resource is currently in.
    The unique ID of the client to which the resource belongs.
    A datetime indicating the lower range of the starting datetime of a booking. Returns all bookings which have a starting time greater than the datetime provided.
    A datetime indicating the upper range of the starting datetime of a booking. Returns all bookings which have a starting time less than the datetime provided.
    A unique ID of a depot to which the booking belongs.
    Flag indicating if the resource is deleted or not. 0 = not deleted, 1 = deleted.
    A job reference number unique to the related depot. Note: this no longer returns a single record as job numbers can be duplicated now that companies can be merged, and legacy records overlap
    A datetime of which the resource was last modified in the format of YYYY-MM-DD HH:mm:ss. Returns records with a last_modified datetime value greater that the datetime provided.
    The unique ID of the project to which the resource belongs.
      
    POST booking
    /api_third_partyv1_booking/booking
    Booking HTTP POST request

    Creates a new booking, and if successful returns information about the created booking.
    Requires 'Booking Write Access' to be enabled in the 'Permissions' section of your Third Party Integration
    @return ARRAY
    Field Description
    format: [YYYY-MM-DD HH:mm:ss]
    [YYYY-MM-DD HH:mm:ss] local time that the call was first booked. (can cause subsequent changes to payroll and invoicing).
    1 or 0 If the latitude and longitude is exact, then set this to 1 Default is 0
    can be quite detailed and long
    1 or 0 If the booking will have roving sites, then set this to 1. Default is 0
    [1 or 0] default is 0
    latitude of address location
    longitude of address location
    format: [YYYY-MM-DD HH:mm:ss]
    (required) 1: unconfirmed, 2: confirmed
    (optional) limited to 255 characters
    limited to 50 characters
    (required) array of integers. each ID refers to a client_contact_id
    limited to 255 characters
    (required) the depot that booking will be delivered from
    [HH:mm:ss]
    Additional information used to find the location
    refers to a client_contact_id
    (required) the project that this booking belongs to. A project belongs to a client
    refers to a client_contact_id
    [HH:mm:ss]
    eg: 12 smith st, Collingwood
    array of integers. each ID refers to a tag_id