Create & Modify Driver Endpoints: PatchDriverEvent

API endpoints for creating, updating, and deleting drivers

PatchDriverEvent

This API permits you to edit a driver Event.

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:Update.

Authentication

Authenticate with the API before running this API.

HTTP Method

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

URL Examples

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

Body (JSON)

Key	Format	Notes	Mandatory
drivereventid	string	Pass the "drivereventid" of the driver event you want to update.	Yes
driver_id	string	Pass the driver_id of the driver you are creating an event against.	No
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

 { "driver_event_id": "101897", "driver_event_code_id": "100001", "event_date": "2024-05-23", "event_value": "Testpatch", "description": "1", "driver_event_action_id": "100001", "due_date": "9-7-2", "completed_flag": "yes", "status_flag": "active" }

Response Details

Validation Messages	Comments
200 OK

{ "driver_event_id": "101897", "driver_id": "101399", "driver_event_code_id": "100001", "event_date": "2024-05-23", "event_value": "Testpatch", "description": "1", "driver_event_value_id": null, "driver_event_description_id": null, "driver_event_action_id": "100001", "due_date": "0009-07-02", "completed_flag": "yes", "attachment_id": null, "user_id_edit": "11244", "last_edit": "2024-05-23 04:23:10", "status_flag": "active", "_links": { "self": { "href": "https://api.test.catch-e.com/fm/driver-events/101897" } }}

{ "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. |

PatchDriverEvents

This API permits you to edit a given list of 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:Update.

Authentication

Authenticate with the API before running this API.

HTTP Method

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

URL Examples

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

Body (JSON)

Key	Format	Notes	Mandatory
drivereventid	string	Pass the "drivereventid" of the driver event you want to update.	Yes
driver_id	string	Pass the driver_id of the driver you are creating an event against.	No
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

[ { "driver_event_id": "101879", "driver_event_code_id": "100006", "event_date": "2024-05-17", "driver_event_action_id": "100001", "status_flag": "active" }, { "driver_event_id": "101878", "driver_event_code_id": "100007", "event_date": "2024-06-20", "driver_event_action_id": "100000", "status_flag": "active" }]

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": "101879", "driver_id": "101313", "driver_event_code_id": "100006", "event_date": "2024-05-17", "event_value": "", "description": "", "driver_event_value_id": null, "driver_event_description_id": null, "driver_event_action_id": "100001", "due_date": "0000-00-00", "completed_flag": "no", "attachment_id": null, "user_id_edit": "11244", "last_edit": "2024-05-17 05:55:41", "status_flag": "active", "_links": { "self": { "href": "https://api.test.catch-e.com/fm/driver-events/101879" } } }, { "driver_event_id": "101878", "driver_id": "101313", "driver_event_code_id": "100007", "event_date": "2024-06-20", "event_value": "", "description": "", "driver_event_value_id": null, "driver_event_description_id": null, "driver_event_action_id": "100000", "due_date": "0000-00-00", "completed_flag": "no", "attachment_id": null, "user_id_edit": "11244", "last_edit": "2024-05-17 05:55:41", "status_flag": "active", "_links": { "self": { "href": "https://api.test.catch-e.com/fm/driver-events/101878" } } } ] }, "total_items": 2}

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

{ "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. |

UpdateDriver

Allows you to update details for a Driver. Creating Audit History records is optional.

Permissions

If you want to use this API in your system, enable Drivers:Update. Audit History records can be created simultaneously and you will need permissions to Audit:UserIdOverride to enable this.

Go to System Roles and select the 'web_services' role
Navigate to the Roles / APIs tab
Find the Drivers:Update permission and check its check box
Find the Audit:UserIdOverride permission and check its check box

Authenticate to api using this method Authenticate with the API, Please refer this link for login information.

HTTP Method

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

Input Fields (Body)

JSON Field	Format	Notes	Mandatory
driver_id	String	Driver ID	Yes
Driver Details	Various	At least one of the available placeholders must be included in the JSON Payload. A full list of placeholders can be obtained by using the fmdrivers tablename in the Request a table data export API.	Yes

Input Fields (JSON)

Example below of updating Addresses for a Driver - Driver ID 100425

{    "addresses": {        "home": {            "home_unit_no": "",            "home_street_no": "",            "address_1": "465 Princess Road",            "address_2": "",            "area": "Southland",            "state": "VIC",            "postcode": "3322",            "country_id": null        },        "post": {            "home_unit_no": "",            "home_street_no": "",            "address_1": "PO Box 5123A",            "address_2": "",            "area": "Southland",            "state": "VIC",            "postcode": "3322",            "country_id": null        }    }}

Successful Response Example

{ "accountant_contact_name": "", "accountant_contact_phone": "", "accountant_firm_name": "", "address_id_home": "100474", "address_id_post": "100475", "addresses": { "home": { "address_1": "465 Princess Road", "address_2": "", "area": "Southland", "state": "VIC", "postcode": "3322", "country_id": null }, "post": { "address_1": "PO Box 5123A", "address_2": "", "area": "Southland", "state": "VIC", "postcode": "3322", "country_id": null } }, ... "_links": { "self": { "href": "https://api.staging.catch-e.com/fm/drivers/100425" } }}

Error Response Details

Validation Messages	Comments
400 - Bad Request

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Bad Request", "status": 400, "detail": "JSON decoding error: Syntax error, malformed JSON"}

{ "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"}

{ "address_id_home": { "noRecordFound": "No record matching the input was found" }, "address_id_post": { "noRecordFound": "No record matching the input was found" }

| You have passed a blank id or one that does not exist. These fields are not required if you have also passed addresses.home and/or addresses.post | |

{ "address_id_home": { "invalidAddressPayload": "You cannot specify both the address_id_home field and addresses.home element" }, "address_id_post": { "invalidAddressPayload": "You cannot specify both the address_id_post field and addresses.post element" }

| These fields are not required as you have also passed addresses.home and/or addresses.post |

UpdateDriverAssets

Overview

Allows you to update Drivers' Asset/s.

HTTP Method

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

Input Fields (Header)

Header should contain the 'Content-Type' Key with the Value = 'application/json' or 'application/hjson'.

Input Fields (Body)

Single Asset update: https://api.test.catch-e.com/fm/driver/assets/

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

JSON Example

Multiple Assets update: https://api.test.catch-e.com/fm/driver/assets/[ { "driver_asset_id": "3196579721328459811", "finance_asset_type_id": "16238640163402548256", "amount": 100077, "description": "An example asset description updated1" }, { "driver_asset_id": "3196579721328459812", "finance_asset_type_id": "16238640163402548256", "amount": 100088, "description": "An example asset description updated2" }]

(Successful) Output Example (sample)

{ "driver_asset_id": 3196434310060077777, "driver_id": 100000, "finance_asset_type_id": 3196195708503888888, "amount": 99.88, "ownership": "debt_free", "description": "Test Asset 2", "finance_asset_type_name": "Shares", "_links": { "self": { "href": "https://api.test.catch-e.com/fm/driver/assets/3196434310060077777" } }}

Error Codes

Example error output

{ "validation_messages": { "driver_asset_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"}

UpdateDriverBankAccount

Allows you to update Driver bank account.

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:Update

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 'PUT' for consuming this web service.

URL Examples

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

Parameters - Path

Key	Format	Notes	Default Value	Mandatory
driverbankaccount_id	string	Driver bank account id to update.		yes

| driverbankaccount | object | Json Payload:

{ "account_name": "string", "claims_access_flag": "yes", "claims_default_flag": "yes", "status_flag": "active"}

Sample Response (200 - Successful)

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