API Access Token

v1_person API

/**
 * REST API end-points for interacting with the 'person' resource.
 * 
 */
Sign in
Available APIs
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_person v1_project v1_resource v1_sage_50 v1_skill v1_tag v1_upload v1_vehicle v1_works_docket
Methods
  • availability GET
  • blocklist GET
  • gender GET
  • person_category GET
  • person_skill GET PUT
  • person_status GET
  • person GET POST PUT
  • pronoun GET
  • social_inclusion GET
    • Help
    Definitions
    T-2.851.1
    Release Notes

    API Release Notes

    Close

    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
    availability
    HTTP GET

    a list of records representing when people are unavailable.
    A binary flag is use dto indicate weather the leave period applies to teh am or pm of each week day in teh "unavailable_shifts" attribute


    unavailable_shifts look up table
    Day: AM : PM
    Mon: 1 : 2
    Tue: 4 : 8
    Wed: 16 : 32
    Thu: 64 : 128
    Fri: 256 : 512
    Sat: 1024 :2048
    Sun: 4096 :8192

    so for example if the person is not available on wednesday and thursday night the a value of the unavailable_shifts would be
    32 + 28 = 60
    A bitwise comparison to the booking can be done with a bitwise comparison between unavailable_shifts and booking_touches_shifts from a booking
    if unavailable_shifts = 0 then all shifts are unavailable

    example data:
    {
    "availability_id": "122",
    "availability_status_id": "2",
    "unavailable_shifts": "0",
    "person_id": "217",
    "availability_type_id": null,
    "availability_was_system_generated": "0",
    "date_from": "2023-09-01 12:00:00",
    "date_to": "2023-09-01 12:00:00",
    "availability_description": null,
    "last_modified": "2023-09-01 05:13:07",
    "modified_by": "15",
    "is_deleted": "0",
    "created_on": "2023-09-01 05:07:08",
    "created_by": "15",
    "first_name": "Alan",
    "last_name": "Lewis",
    "depot_id": "1",
    "author": "Debra Collins",
    "edited_by": "Debra Collins",
    "reviewed_by": null,
    "availability_type_name": null,
    "territory_id": null,
    "depot_name": "Mydo",
    "max_last_modified": "2023-09-01 06:27:14.9577"
    }

    @return array of resources. Returns a single record if the person_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.
    Primary key of the record
    The unique ID of the depot to which the resource belongs.
    coma separated list of depot_ids
    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 desired resource. Returns a single record if it exists. Other filters do not apply.
    coma separated list of territory_ids
      
    blocklist
    HTTP GET

    a list of records representing people that are blocklisted from working with certain clients.
    Sample response data:
    {
    "blocklist_code": "client_blocklist-125-217",
    "blocklist_type_id": "1",
    "blocklist_type_code": "client_blocklist",
    "blocklist_type_name": "Client Blocklist",
    "person_id": "217",
    "first_name": "Alan",
    "last_name": "Lewis",
    "blocklist_reason": "Aren't allowed for some reason",
    "client_id": "125",
    "project_ids": [],
    "project_id": null,
    "client_contact_ids": [],
    "client_contact_id": null,
    "person_ids": [
    "217"
    ],
    "person_names": "Alan Lewis",
    "blocked_from": "Client: Abata",
    "is_deleted": "0",
    "last_modified": "2024-04-04 19:10:44",
    "modified_by": "15",
    "modified_by_name": "John Smith",
    "created_on": "2024-04-04 19:10:44",
    "created_by": "15",
    "created_by_name": "John Smith",
    "max_last_modified": "2024-04-10 19:44:08.5591"
    }
    @return ARRAY
    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 concatenated code of the blocklist.
    The ID of the blocklist type. E.g. 1=client_blocklist, 2=project_blocklist, 3=client_contact_blocklist, 4=persons_blocklist.
    Set to '1' if you want only deleted records, '0' for non-deleted records.
    (YYYY-MM-DD HH:mm:ss), if supplied, only records modified more recently than this date
    The ID of the person.
      
    look up table of all genders
    @return ARRAY
    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.
    if specified, then only a single gender will be returned
    no genders have been deleted (yet)
      
    Returns information about the 'person_category' resource (referred to as 'resource' below) filterable by the fields described below.
    The person_category resource is dynamic and can be modified by the end user via the interface.
    Resource response fields:
    - 'person_category_id' (primary key, number): The ID of the person_category resource.
    - 'person_category_abbreviation' (string): The abbreviation of the resource name.
    - 'person_category_title' (string): The human readable name of the resource.
    - 'person_category_description' (string): The human readable description of the resource.
    - 'is_deleted' (boolean): Whether the resource is considered deleted or not.
    - 'created_on' (datetime): The date and time that the resource was originally created on.
    - 'last_modified' (datetime): The date and time that the resource was last modified.
    - 'max_last_modified' (datetime): The date and time that the resource is being requested. Used to query for only resources that have changed after this date and time on subsequent requests.
    @return array of resources. Returns a single record if the person_category_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.
    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 desired resource. Returns a single record if it exists. Other filters do not apply.
      
    Returns information about the 'person_skill' resource, filterable by the fields described below.
    Gets skills for a person.

    Resource response fields:
    - 'skill_id' (primary key, number): The ID of the skill resource.
    - 'person_id' (primary key, number): The ID of the person resource.
    - 'resource_id' (foreign key, number): Each skill can be of a specific resource type eg: traffic controller, spotter
    - 'depot_id' (foreign key, number): The ID of the depot resource.
    - 'max_last_modified' (datetime): The date and time that the skill is being requested. Used to query for only skills that have changed after this date and time on subsequent requests.
    - 'is_deleted' (boolean): Whether the skill is considered deleted or not.
    @return ARRAY of person_skill
    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.
    Set to '0' to undelete the record.
    (YYYY-MM-DD HH:mm:ss), if supplied, only records modified more recent than this datetime will be returned
      
    This method creates and updates a person skill and if succesful will return the details of the person skill.

    Resource response fields:
    - 'skill_id' (primary key, number): The ID of the skill resource.
    - 'person_id' (primary key, number): The ID of the person resource.
    - 'driver_licence_type_id' (foreign key, number): The ID of the driver licence type resource.
    - 'date_gained' (datetime): The date from which this skill was gained.
    - 'expires_on' (datetime): The date which this skill is set to expire.
    - 'skill_reference' (string): Reference code for skill eg. licence number.
    - 'person_skill_comment' (text): General comments about this person skill.
    - 'is_deleted' (boolean): Whether the skill is considered deleted or not.
    @return ARRAY
    Field Description
    format: date
    Type of drivers license required for this skill.
    format: date
    (required)
    (required)
      
    Returns information about the 'person status' resource (referred to as 'resource' below) filterable by the fields described below.
    This is lookup table, as person status does not change.
    Resource response fields:

    - 'person_status_id' (primary key, number): The ID of the person status resource.
    - 'person_status_name' (string): The name of the person status resource.
    - 'person_status_approved' (boolean): Whether the person status is approved for the person to be an available resource in Traffio.
    - 'is_deleted' (boolean): Whether the resource is considered deleted or not.
    @return ARRAY of person statuses
    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.
      
    Returns information about the 'person' resource (referred to as 'resource' below) filterable by the fields described below.
    The person_category resource is dynamic and can be modified by the end user via the interface.
    Resource response fields:
    - 'person_id' (primary key, number): The ID of the person resource.
    - 'depot_id' (foreign key, number): The ID of the depot resource that the record belongs to.
    - 'person_status_id' (foreign key, number): The ID of the person status resource.
    - 'person_category_id' (foreign key, number): The ID of the person_category resource that the record belongs to.
    - 'tag_ids' (number set): A set of tag resource IDs related to the record.
    - 'first_name' (string): The first name of the person.
    - 'last_name' (string): The last name of the person.
    - 'mobile' (string): The phone number of the person.
    - 'email' (string): The email address of the person.
    - 'employee_reference' (string): The internal reference number for the person for employment purposes.
    - 'person_is_office_only' (boolean): Whether the person only works in an officeadministrative capacity and not on bookings.
    - 'person_is_sub_contractor' (boolean): Whether the person is subcontracted and not employed directly.
    - 'person_category_title' (string): The human readable name of the category that the resource belongs to. Corresponds to the 'person_category_id' field.
    - 'resource_name' (string): The human readable name of the type of workbooking resource (as opposed to a data resource) that the resource belongs to.
    - 'is_deleted' (boolean): Whether the resource is considered deleted or not.
    - 'created_on' (datetime): The date and time that the resource was originally created on.
    - 'last_modified' (datetime): The date and time that the resource was last modified.
    - 'max_last_modified' (datetime): The date and time that the resource is being requested. Used to query for only resources that have changed after this date and time on subsequent requests.
    @return array of resources. Returns a single record if the person_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 depot to which the resource belongs.
    The internal reference number for the person for employment purposes.
    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 desired resource. Returns a single record if it exists. Other filters do not apply.
    Whether the person only works in an office
    Whether the person is subcontracted and not employed directly. 0 = false, 1 = true.
    The ID(s) of the person status resource (comma separated).
      
    POST person
    /api_third_party/v1_person/person
    Creates a user and if successful will return the details of the new user.
    @return ARRAY
    Field Description
    Method to use to contact the person. Can be 'sms', 'email' or 'both.
    The birth date of the person in the format YYYY-MM-DD
    This is the depot the person belongs to. Required.
    Required.
    use the GET gender API lookup for values
    Required.
    Required.
    Whether the person should be notified of their account details. Defaults to not notifying the user. 0 = no, 1 = yes.
    format YYYY-MM-DD Date which the person is Active from
    format YYYY-MM-D Date which the person is Terminated from
    Formatted address from google map according to lat long
    0 = no, 1 = yes.
    0 = no, 1 = yes.
    Latitude of address location
    Longtitude of address location
    format YYYY-MM-DD Date which the person is on Probation from
    format YYYY-MM-DD Date which the person first starts work
    The unique ID of the person status resource.
    us the GET pronoun API look up for values
    The resource that identifies the person.
    is the person aproved to be a team leader. 0 = no, 1 = yes.
    User name of the person used to login. This will be converted to lowercase. Required.
      
    Creates a user and if successful will return the details of the new user.
    @return ARRAY
    Field Description
    The birth date of the person in the format YYYY-MM-DD
    use the GET gender API lookup for values
    .
    Formatted address from google map according to lat long
    Required Traffio's primary key for this person
    us the GET pronoun API look up for values
      
    look up table of all pronouns
    @return ARRAY
    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.
    no pronouns have been deleted (yet)
    if specified, then only a single pronoun will be returned
      
    look up table of all social_inclusions
    @return ARRAY
    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.
    no social_inclusions have been deleted (yet)
    if specified, then only a single social_inclusion will be returned