ChangeContractDriver

This method changes the driver by creating a driver change event and optionally saves an odometer record.

Supplementary SWAGGER documentation is available here: https://api.catch-e.com/docs/#/Contract%20%2F%20Events/changeContractDriver

Permissions

To run this API, the nominated 'web-services' role needs to be given permission.

If you are not actively using the API, leave the permission off for better security.

Go to Roles / APIs and check on ContractEvents:ChangeDriver.

HTTP Method

Use the HTTP Method 'POST' for consuming this web service.

URL Examples

https://api.test.catch-e.com/fm/contract/events/{contract_id}/change-driver

https://api.test.catch-e.com/fm/contract/events/102746/change-driver

Parameters - Path Variables

Key

Format

Notes

Mandatory

contract_id

string

Target contract ID to edit

Yes

Headers

Key

Format

Notes

Mandatory

Audit-User-Id

string

Pass a user_id here to create audit records with this user's details. This can only be done if the authenticated API user has Roles / APIs checked for the permission Audit:UserIdOverride

No

Body (JSON)

JSON

Field Format

Notes

Mandatory

driver_id

string

Driver ID to change to. Only drivers linked to the contract's client or client group will be accepted

Yes

event_date

string (date)

Effective date of the contract event. If no date is passed, the system date will be used. Format: YYYY-MM-DD or 0000-00-00 to leave blank. A blank date is used when the first driver is being added when a quote is accepted. Required if odometer is passed

No

description

string

Event description

No

odometer

number

Odometer reading value. A maintenance ODO record is created when the event is saved. An event_date is required if an odometer is passed

No

contract_event_action_id

string

Contract event action ID

No

due_date

string (date)

Due date for the event. Format: YYYY-MM-DD

No

completed_flag

string

If not passed, respects default from DRIVER Posting Classes / Details "Event Completed" field

No

override_warnings_flag

string

Pass as 'yes' to override warnings about invalid odometer readings. If not passed, defaults to 'no'

No

Input Fields (JSON)

{ "driver_id": "100002", "event_date": "2021-03-03", "description": "API TEST", "odometer": 565, "contract_event_action_id": "100000", "due_date": "2022-08-02", "completed_flag": "no", "override_warnings_flag": "yes" }

Response Details

Validation Message

Comments

201 Created

A successful response returns the newly created driver change event

404 - Not Found

API endpoint not found

422 - Unprocessable Entity

Failed validation - see error examples for specific validation issues

403 - Forbidden

You do not have permissions for this request

Successful Response Example

{ "contract_event_id": "108115", "contract_id": "102761", "posting_class_id": "100033", "attachment_id": null, "event_date": "2021-03-03", "table_name": "fm_drivers", "record_id": "100220", "event_value": "Blandin, Jimbo", "description": "API TEST", "contract_event_value_id": null, "contract_event_description_id": "0", "contract_event_action_id": "100000", "due_date": null, "completed_flag": "yes", "event_amount": 0, "message_type": null, "user_id": "11140", "last_edit": "2022-04-06 11:17:21", "status_flag": "active" }

Error Response Examples

422 Unprocessable Entity - Invalid Odometer

{ "description": "Based on a system estimate, this odometer is not valid!" }

The odometer reading provided is not valid based on system estimates. This warning can be ignored if the override_warnings_flag is set to 'yes'.

422 Failed Validation - Invalid contract_id

{ "detail": "Failed Validation", "contract_id": { "noRecordFound": "No record matching the input was found" } }

The contract_id passed is not stored in the database.

422 Failed Validation - Invalid date format

{ "detail": "Failed Validation", "event_date": "invalidDate" }

You must enter a valid date as YYYY-MM-DD or 0000-00-00.

422 Failed Validation - Invalid driver_id

{ "detail": "Failed Validation", "driver_id": { "noRecordFound": "No record matching the input was found" } }

The driver_id passed is not stored in the database.

422 Failed Validation - Driver not linked to client

{ "detail": "Failed Validation", "driver_id": { "driverNotLinkedToClient": "The input driver is not associated with the contract client" } }

The driver_id passed is not associated with the client in the contract.

422 Failed Validation - Odometer requires date

{ "validation_messages": { "odometer": { "odometerRequiresNonZeroDate": "event_date cannot be 0000-00-00" } } }

If you pass an odometer reading, a date is also required.

403 Forbidden

{ "detail": "Forbidden" }

You do not have permissions for this request.