Driver assignations API – FMS documentation

1. Description

Driver assignations API is used for making driver assignments to objects (vehicles). This allows webusers who have generated their API key to create driver assignations or get latest assignation using API calls.

2. API version 1

2.1. Create Assignation
2.1.1. Request with datetime

POST /driver/assignations?version=1&api_key=<...>
HOST: api.fm-track.com
Content-Type: application/json;charset=UTF-8
 
BODY:
    {
    "driver_id": "240afea1-84ae-43ec-8139-f13cfa2f3094",
    "object_id": "7bf8990c-dba6-11e9-bdfc-1ff21de66015",
    "event_type": "START"
    "datetime":"2021-07-01T08:50:23.893Z"
    }

2.1.2. Request without datetime

POST /driver/assignations?version=1&api_key=<...>
HOST: api.fm-track.com
Content-Type: application/json;charset=UTF-8
 
BODY:
    {
    "driver_id": "240afea1-84ae-43ec-8139-f13cfa2f3094",
    "object_id": "7bf8990c-dba6-11e9-bdfc-1ff21de66015",
    "event_type": "START"
    }

	Parameter	Type	Description	Is required	Validation
1	version	string	Version of API	+
2	api_key	string	User identification key	+
3	driver_id	string	Driver identifier, External driver ID	+
4	object_id	string	Object identifier, External object ID	+
5	event_type	string	Event type	+	Possible values: START, STOP
6	datetime	string	Datetime for START or STOP event	-	ISO 8601 datetime

2.1.3. Response for correct request

{
    "object_id":"7bf8990c-dba6-11e9-bdfc-1ff21de66015",
    "driver_id":"240afea1-84ae-43ec-8139-f13cfa2f3094",
    "event_type":"START",
    "datetime":"2021-07-01T08:50:23.893Z"
}

	Parameter	Type	Description
1	driver_id	string	Driver identifier, External driver ID
2	object_id	string	Object identifier, External object ID
3	event_type	string	Event type
4	datetime	string	Datetime of START or STOP event

2.1.4. Responses for incorrect request

{
    "code": 422,
    "message": "Validation failed, see 'fieldValidationErrors' for more details",
    "field_validation_errors": [
        {
            "field": "objectId",
            "reason": "must not be empty",
            "rejected_value": "<null value>"
        },
        {
            "field": "driverId",
            "reason": "must not be empty",
            "rejected_value": "<null value>"
        },
        {
            "field": "eventType",
            "reason": "must not be null",
            "rejected_value": "<null value>"
        }
    ]
}

{
    "code": 400,
    "message": "Please provide valid driver assignation event type START|STOP"
}

{
    "code": 400,
    "message": "Invalid format: \"1993 05 04\" is malformed at \" 05 04\""
}

{
    "code": 404,
    "message": "Object with id 7bf8990c-dba6-11e9-bdfc-1ff21de66015asdasdasdasdasdadas not found"
}

{
    "code": 404,
    "message": "Driver with id 240afea1-84ae-43ec-8139-f13casfa2f3094 not found"
}

Parameter	Description
code	Error code 400 - server cannot or will not process the request due to an apparent client error; 404 - requested resource could not be found but may be available in the future;
message	Error code message

2.2. Get last Assignation
2.2.1. Request byObjectID

GET /driver/assignations/last?version=1&byObjectId={objectId}&api_key=<...>
HOST: api.fm-track.com
Content-Type: application/json;charset=UTF-8

2.2.2. Example byObjectID

GET /driver/assignations/last?version=1&byObjectId=7bf8990c-dba6-11e9-bdfc-1ff21de66015&api_key=L6fwb1xODwA95qF7ybXJ4S2cSM49h1Wj
HOST: api.fm-track.com
Content-Type: application/json;charset=UTF-8

2.2.3. Request byDriverId

GET /driver/assignations/last?version=1&byDriverId={driverId}&api_key=<...>
HOST: api.fm-track.com
Content-Type: application/json;charset=UTF-8

2.2.4. Example byDriverId

GET /driver/assignations/last?version=1&byDriverId=240afea1-84ae-43ec-8139-f13cfa2f3094&api_key=L6fwb1xODwA95qF7ybXJ4S2cSM49h1Wj
HOST: api.fm-track.com
Content-Type: application/json;charset=UTF-8

	Parameter	Type	Description	Is required	Validation
1	version	string	Version of API	+
2	api_key	string	User identification key	+
3	byDriverId	string	Driver identifier, External driver ID	+	Either byDriverId or byObjectId is required
4	byObjectId	string	Object identifier, External object ID	+	Either byDriverId or byObjectId is required

2.2.5. Response for correct request

{
    "object_id":"7bf8990c-dba6-11e9-bdfc-1ff21de66015",
    "driver_id":"240afea1-84ae-43ec-8139-f13cfa2f3094",
    "event_type":"STOP",
    "datetime":"2021-07-01T08:50:28.893Z"
}

	Parameter	Type	Description
1	driver_id	string	Driver identifier, External driver ID
2	object_id	string	Object identifier, External object ID
3	event_type	string	Event type
4	datetime	string	Datetime of START or STOP event

2.2.6. Responses for incorrect request

{
    "code": 400,
    "message": "No query parameters were provided. Provide query parameters byDriverId or byObjectId"
}

{
    "code": 404,
    "message": "Driver assignation event by driver id 8200f935-4970-43e3-8ab2-220c7f6463f4 not found"
}

{
    "code": 404,
    "message": "Driver with id 240afea1-84ae-43ec-8139-f13cfa2f3a094 not found"
}

{
    "code": 404,
    "message": "Object with id 7bf8990c-dba6-11de9-bdfc-1ff21de66015 not found"
}

Parameter	Description
code	Error code 400 - server cannot or will not process the request due to an apparent client error; 404 - requested resource could not be found but may be available in the future;
message	Error code message