Create & Modify Driver Endpoints: ChangeContractDriver

API endpoints for creating, updating, and deleting drivers

ChangeContractDriver

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

Supplementary SWAGGER documentation is available here:

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.demo.catch-e.com/authenticate

https://api..catch-e.com/authenticate

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

Input Fields (Body)

JSON Field	Format	Notes	Mandatory
driver_id	string	Pass the driver_id of the driver you are changing to. Only drivers linked to the contract's client or client group will be accepted.	yes
event_date	string($date)	Pass the effective date of the contract event you are creating. If no date is passed, the system date will be used. If you want to set the date to be blank, you can pass a date of '0000-00-00'. A blank date is used in the system when the first driver is being added when a quote is accepted. If you are also passing an odometer reading, a date is required here.	no
description	string		no
odometer	number	Pass an odometer value to record the odometer reading on a driver change. A maintenance ODO record is created when the event is saved. An event_date is required if an odometer is passed.	no
contracteventaction_id	string		no
due_date	string($date)		no
completed_flag	string	If not passed, the setting in the 'DRIVER' Posting Classes / Details "Event Completed" field is used.	no
overridewarningsflag	string	Pass this as 'yes' to override warnings about invalid odometer readings. If not passed, this 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"}

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 Details

Validation Messages	Comments
404 Not Found
"detail": "API endpoint not found"
422 Unprocessable Entity
"description": "Based on a system estimate, this odometer is not valid!"	This warning can be ignored if the overridewarningsflag is set to ‘yes’
422 Failed Validation
"detail": "Failed Validation" {"contract_id": {"noRecordFound": "No record matching the input was found"}}	The contract_id passed is not stored in the database. E.g. '1'
"detail": "Failed Validation" Invalid_date	You must enter a valid date as DD/MM/YYYY, or 0.
"detail": "Failed Validation"\	{" driver_id": {"noRecordFound": "No record matching the input was found"}}

{" driver_id": "driverNotLinkedToClient": "The input driver is not asosiated with the contract client" }}

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

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

CreateDriverAssets

Overview

Allows you to add new Drivers' Asset/s.

HTTP Method

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

Input Fields (Header)

Header should contain the 'Content-Type' Key with the Value = 'application/json' or 'application/hjson'.
Header should contain the 'Accept' Key with the Value = 'application/vnd.catch-e-api.v1+json, application/problem+json'

Input Fields (Body)

JSON Field	Format	Notes	Mandatory
driver_id	Int	Driver ID	Yes
financeassettype_id	string	Enter the financeassettype_id for the respective Asset Type. See GetFinanceAssetTypes)	Yes
amount	number	Enter the Asset Value.	Yes
description	string	Enter the Asset Description.	No

JSON Example

https://api.catch-e.com/fm/driver/assets/[ { "driver_id": "101175", "finance_asset_type_id": "16238640163402548256", "amount": "77777.00", "description": "Matt Test Asset 1" }, { "driver_id": "101175", "finance_asset_type_id": "16238640163402548256", "amount": "88888.00", "description": "Matt Test Asset 2" }]

(Successful) Output Example (sample)

{ "driver_asset_id": 3196434310060077777, "driver_id": 101211, "finance_asset_type_id": 3196195708503877777, "amount": 77777, "ownership": "debt_free", "description": "Test Asset 1", "finance_asset_type_name": "Resident Property", "_links": { "self": { "href": "https://api.catch-e.com/fm/driver/assets/3196434310060077777" } }}

Error Codes

Example error output

{ "validation_messages": { "amount": { "isEmpty": "Value is required and can't be empty" } }, "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unprocessable Entity", "status": 422, "detail": "Failed Validation"}

CreateDriverBankAccounts

Allows you to CreateDriverBankAccounts

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 DriverBankAccounts:Create

Note: This API is not configured for external use.
Contact your Account Manager to discuss access to this API.

HTTP Method

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

URL Examples

https://api.catch-e.com/bank/accounts

Parameters - Path

Key	Format	Notes	Mandatory
bank_accounts	string	Pass the bank_accounts to create driver bank account.	yes
Delegated-Locking-Session-Id	string	Locking responsibility will be delegated to the specified Session Id.	no
Audit-User-Id	string	User Id to use for audit purposes.	no

Sample Response (200 - Successful)

{ "driver_bank_account_id": "string", "driver_id": "string", "account_name": "string", "bsb": "string", "account_number": "string", "claims_access_flag": "no", "claims_default_flag": "no", "status_flag": "active"}

CreateDriverEvents

This API permits you to create one or multiple Driver Events.

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 DriverEvents:Create.

Authentication

Authenticate with the API before running this API.

HTTP Method

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

URL Examples

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

Parameters - Path Variables

Key	Format	Notes	Mandatory
driver_id	string	Target Driver 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
Time-Zone	string	Driver events will be created in the specified timezone. The timezone value can be given in several formats, none of which are case sensitive: As a named time zone, such as 'Europe/Helsinki', 'US/Eastern', or 'MET'. As a string indicating an offset from UTC of the form :MM, prefixed with a + or -, such as '+10:00', '-6:00', or '+05:30' A leading zero can optionally be used for hours values less than 10; Default value : UTC	No

Body (JSON)

Key	Format	Notes	Mandatory
driver_id	string	Pass the driver_id of the driver you are creating an event against.	Yes
drivereventcode_id	string	Pass a valid eventcodeid for the type of event you want to create.	Yes
event_date	string	Pass the effective date of the driver event you are creating. If no date is passed, the system date will be used. If you want to set the date to be blank, you can pass a date of '0000-00-00'.	No
event_value	string	An event value can be passed. This will be ignored if there is an eventvalueid or the eventvalueid validation fails.	No
drivereventvalue_id	string	Pass a drivereventvalue_id if the event uses a configured list of event values. Use the API getDriverEventValues to get a list of available values. You do not need to pass a value if there is no configured list or you want to use the stored default value.	conditional
description	string	Pass an event description if the event does not have a stored list of descriptions. This will be ignored if there is an eventdescriptionid or the eventdescriptionid validation fails.	Yes
drivereventdescription_id	string	Pass the drivereventdescription_id if there is a configured list of event descriptions. Use the API getDriverEventDescriptions to get a list of available descriptions. You do not need to pass a value if there is no configured list or you want to use the stored default description.	conditional
drivereventaction_id	string	Pass an action from the actions stored in . Use the API getDriverEventActions to get a list of available actions. If no action is passed, the default value is 100000.	No
due_date	string	Pass the due date of the contract event you are creating if required.	No
completed_flag	string	If not passed, the default setting is used. This is stored as "Yes", "No".	No
attachment_id	string	Link a Driver Event to an Attachment ID.	No
useridedit	string	Last Edit By (User ID)	No
last_edit	string	Last Edit timestamp	No
status_flag	string	Event Status ('active','deleted')	No

JSON Sample

Single Driver Event

[ { "driver_id" : "101018", "driver_event_code_id": "100001", "event_date": "2024-06-01", "event_value": "1", "description": "Event code: Reminder (API)", "driver_event_action_id": "100000", "due_date": "2024-07-01", "status_flag": "active", "completed_flag": "yes" }]

Multiple Driver Events

[ { "driver_id" : "100006", "driver_event_code_id": "100004", "event_date": "2024-06-01", "event_value": "1", "description": "Event code: Quote Accepted (API)", "driver_event_action_id": "100000", "due_date": "2024-07-01", "status_flag": "active", "completed_flag": "yes" }, { "driver_id" : "100007", "driver_event_code_id": "100005", "event_date": "2024-06-01", "event_value": "2", "description": "Event code: Documents Sent (API)", "driver_event_action_id": "100001", "due_date": "2024-07-01", "status_flag": "active", "completed_flag": "yes" }]

Response Details

Validation Messages	Comments
200 OK

{ { "_links": { "self": { "href": "https://api.test.catch-e.com/fm/driver-events/" } }, "_embedded": { "fm_driver_events": [ { "driver_event_id": "101935", "driver_id": "100006", "driver_event_code_id": "100004", "event_date": "2024-06-01", "event_value": "1", "description": "Event code: Quote Accepted (API)", "driver_event_value_id": null, "driver_event_description_id": null, "driver_event_action_id": "100000", "due_date": "2024-07-01", "completed_flag": "yes", "attachment_id": null, "user_id_edit": "11244", "last_edit": "2024-06-04 01:33:25", "status_flag": "active", "_links": { "self": { "href": "https://api.test.catch-e.com/fm/driver-events/101935" } } } ] }, "total_items": 1}

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unauthorized", "status": 401, "detail": "Unauthorized"}

| You have not authenticated before running this API or The token_timeout of the current session has passed. You need to authenticate again. |
| 403 - Forbidden | | |

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Forbidden", "status": 403, "detail": "Forbidden"}

| You do not have permissions for this request. Go to System Roles and enter 'web_services' Navigate to the Roles / APIs tab to make sure the permission you need to run this API is checked. |
| 422 - Unprocessable Content | | |

{ "validation_messages": [ { "attachment_id": { "noRecordFound": "No record matching the input was found" } } ], "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unprocessable Entity", "status": 422, "detail": "Failed Validation"}

| Attachment ID not found/valid. |

CreateDriverLiabilities

Overview

Allows you to add new Drivers' Liabilities.

HTTP Method

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

Input Fields (Header)

Header should contain the 'Content-Type' Key with the Value = 'application/json' or 'application/hjson'.
Header should contain the 'Accept' Key with the Value = 'application/vnd.catch-e-api.v1+json, application/problem+json'

Input Fields (Body)

JSON Field	Format	Notes	Mandatory
driver_id	Int	Driver ID	Yes
financeliabilitytype_id	string	Enter the financeliabilitytype_idfor the respective Liability Type. See GetFinanceLiabilityTypes)	Yes
financeliabilityfinancier_id	string	Enter the financeliabilityfinancier_id for the respective Liability Financier. See getFinanceLiabilityFinanciers)	Yes
amount	number	Enter the Liability Value.	Yes
description	string	Enter the Liability Description.	No

JSON Example

[ { "driver_id": "100000", "finance_liability_type_id": "2196195708503852111", "finance_liability_financier_id": "4196195708503852222", "driver_asset_id": "4196296702502852222", "amount": 123456.78, "monthly_payment_amount": 1234.56, "liability_payout_flag": "no", "liability_end_date": "2022-05-01", "liability_limit_amount": 0 }, { "driver_id": "100000", "finance_liability_type_id": "2196195708503852111", "finance_liability_financier_id": "4196195708503852222", "driver_asset_id": "4196296702502852223", "amount": 456.78, "monthly_payment_amount": 34.56, "liability_payout_flag": "no", "liability_end_date": "2022-05-01", "liability_limit_amount": 0 }]

(Successful) Output Example (sample)

{ "driver_liability_id": 3196434310060049502, "driver_id": 101211, "finance_liability_type_id": 3196195708503852473, "finance_liability_financier_id": 3196195708503852478, "driver_asset_id": null, "amount": 1000.77, "monthly_payment_amount": 12.34, "liability_payout_flag": "no", "liability_end_date": "2025-01-01", "liability_limit_amount": 1111.11, "finance_liability_type_name": "Credit Card Limit", "finance_liability_financier_name": "ANZ Banking", "_links": { "self": { "href": "https://api.catch-e.com/fm/driver/liabilities/3196434310060049502" } }}

Error Codes

Example error output

{ "validation_messages": { "liability_end_date": { "dateInvalidDate": "The input does not appear to be a valid date" } }, "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unprocessable Entity", "status": 422, "detail": "Failed Validation"}