Create & Modify Driver Endpoints: CreateDrivers

CreateDrivers

This method creates a driver or drivers.

Supplementary SWAGGER documentation is available here: https://api.catch-e.com/docs/#/Drivers/createDrivers(https://api.catch-e.com/docs/#/Drivers/createDrivers)

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

HTTP Method

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

URL Examples

https://api.catch-e.com/fm/drivers

Headers

Body (JSON)

Input Fields (JSON)

{ "client_id": "100309", "given_name": "Jimi", "surname": "Hendrix", "home_email": "jimi@efg.com"}

Response Details

{ "_links": { "self": { "href": "https://api.test.catch-e.com/fm/drivers" } }, "_embedded": { "fm_drivers": [ { "accountant_contact_name": "",...

| A successful response returns all fields in the new table record. |
| 422 Unrocessable Entity | | |

"client_id": { "duplicateDriverRecord": "An existing driver record exist for the given name, email address and client." }

| It looks like this driver already exists. | |

"detail": "given_name": { "isEmpty": "Value is required and can't be empty"

| You have not passed one of the four mandatory KEYS. A new driver record has not been created. | |

"detail": "Unrecognized fields: midle_name"

| You have passed a field name that does not exist. Check and try again. The available fields are available in the supplementary SWAGGER documentation here: https://api.catch-e.com/docs/#/Drivers/createDrivers(https://api.catch-e.com/docs/#/Drivers/createDrivers) |
| 403 - Forbidden | | |

|"detail": "Forbidden"

| You do not have permissions for this request. |

CreateDrivers

Allows you to create a new Driver record. Creating Audit History records is optional.

Permissions

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

1. Go to System Roles and select the 'web_services' role

2. Navigate to the Roles / APIs tab

3. Find the Drivers:Create permission and check its check box

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

Input Fields (Body)

Input Fields (JSON)

{ "client_id":"100002", "given_name":"Mary", "surname":"Hopkins", "home_email":"mary.hopkins@vic.com.au"}

Successful Response Example

{ "_links": { "self": { "href": "https://api.staging.catch-e.com/fm/drivers" } }, "_embedded": { "fm_drivers": [ { "accountant_contact_name": "", "accountant_contact_phone": "", "accountant_firm_name": "", "address_id_home": null, "address_id_post": null, "addresses": [], "allowances": 0, "annual_salary": 0, "asset_bank_accounts": null, "asset_bank_accounts_description": "", "asset_furniture": null, "asset_furniture_description": "", "asset_investment_properties": null, "asset_investment_properties_description": "", "asset_motor_vehicle": null, "asset_motor_vehicle_description": "", "asset_other_investments": null, "asset_other_investments_description": "", "asset_resident_property": null, "asset_resident_property_description": "", "asset_shares": null, "asset_shares_description": "", "asset_super": null, "asset_super_description": "", "ato_loan_flag": "no", "australian_resident": "yes", "card_account_number": "", "client_cost_centre_id": null, "client_id": "100002", "contact_note": null, "corporate_type_id_previous_employer": "0", "created": "2021-08-30 03:40:07", "credit_check_authorised_flag": null, "date_of_birth": null, "driver_claims_flag": "yes", "driver_employment_type_id": "0", "driver_id": "101224", "driver_id_external": "0", "driver_lic_exp": null, "driver_licence": null, "driver_licence_state": null, "driver_occupation_code_id": "0", "employee_alias": "", "employee_area": null, "employee_end": "0000-00-00", "employee_group": null, "employee_no": null, "employee_pay_office": null, "employee_sl_acc": null, "employee_start": "0000-00-00", "employee_super": 0, "employer_address_1": "", "employer_address_2": "", "employer_address_3": "", "employer_address_postcode": "", "employer_address_state": null, "employer_super": 0, "expense_credit_card": null, "expense_household": null, "expense_mortgage": null, "expense_other": null, "expense_private_education_childcare": null, "expense_rent": null, "expense_vehicle": null, "external_code": "", "fbt_type": null, "financier_applicant_reference": "", "gender": null, "generated_password": null, "given_name": "Mary", "home_car_postcode": null, "home_email": "mary.hopkins@vic.com.au", "home_fax": null, "home_phone": null, "home_postcode": null, "home_state": null, "home_street": null, "home_street_no": null, "home_street_type": null, "home_suburb": null, "home_unit_no": null, "income_government_benefits": null, "income_gross": null, "income_investment": null, "income_net": null, "income_other": null, "income_rental_net": null, "income_spouse_gross": null, "income_spouse_net": null, "income_superannuation": null, "insurance_broker_fee_exempt_flag": "yes", "kyc_verified_flag": "no", "landlord_name": "", "landlord_telephone": "", "last_edit": "2021-08-30 03:40:07", "liability_credit_card_limit": null, "liability_credit_card_limit_description": "", "liability_investment_mortgages": null, "liability_investment_mortgages_description": "", "liability_loans": null, "liability_loans_description": "", "liability_mortgages": null, "liability_mortgages_description": "", "liability_other": null, "liability_other_description": "", "liability_overdraft": null, "liability_overdraft_description": "", "liability_rent": null, "liability_rent_description": null, "licence_class": "", "marital_status": null, "middle_name": "", "mobile": null, "name_on_account": "", "no_of_dependents": null, "pay_cycle_id": "0", "preferred_name": null, "previous_address_1": "", "previous_address_2": "", "previous_address_3": "", "previous_address_country_id": null, "previous_address_postcode": "", "previous_address_state": null, "previous_address_years_at_address": 0, "previous_employer_name": "", "previous_employer_phone": "", "previous_years_employed": 0, "report_delivery_type": "email", "residency_status": null, "residential_status": null, "salutation": null, "start_at_address": "0000-00-00", "stop_becs_flag": "no", "supplier_id_etag": "0", "supplier_id_financier": "0", "surname": "Hopkins", "tag_account_number": "", "tag_number": "", "user_id_assigned": null, "user_id_create": 10824, "user_id_edit": "10824", "user_id_package_advisor": null, "work_contact_given": null, "work_contact_position": null, "work_contact_surname": null, "work_fax": null, "work_name": null, "work_phone": null, "work_phone_ext": null, "work_position": null, "work_postcode": null, "work_state": null, "work_street": null, "work_street_no": null, "work_street_type": null, "work_suburb": null, "work_type": null, "work_unit_no": null, "years_at_address": 0, "years_with_employer": 0, "_links": { "self": { "href": "https://api.staging.catch-e.com/fm/drivers/101224" } } } ] }, "total_items": 1}

Error Response Details

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

| The JSON payload content is not formatted correctly. |
| 401 - Unauthorized | | |

{ "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 - Failed Validation | | |

{ "validation_messages": [ { "client_id": { "duplicateDriverRecord": "An existing driver record exist for the given name, email address and client." } } ], "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unprocessable Entity", "status": 422, "detail": "Failed Validation"}}

| Driver Record already exists with 4 mandatory fields | |

{ "validation_messages": [ { "client_id": { "isEmpty": "Value is required and can't be empty" }, "given_name": { "isEmpty": "Value is required and can't be empty" }, "home_email": { "isEmpty": "Value is required and can't be empty" }, "surname": { "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"}}

| If a request to create a new Driver has one or more of these mandatory fields missing, an error will be thrown. Mandatory fields must be included. | |

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

| Client ID is not recognised. |

DeidentifyDriverData

Use this method to deidentify driver data.

The mechanism for this is a query that selects the target drivers for this process.

You may want to deidentify drivers after a time when they no longer hold active contracts in your system for their privacy and security.

A standard query is available for expected selections you might use in this job.

Review this with your Account Manager and refine the selections to meet your requirements.

Warning: When run, the updates made in a DeidentifyDriverData job are not reversable.
Test and check your updates carefully before running in your Live environment.

Outcomes

1. Driver and related tables are updated
2. Values are replaced with unusable data
3. Numeric fields are set to 0.
4. A driver event logging the date of deidentification is created.

Field Descriptions

DeleteDriverAssets

Overview

Allows you to Delete Driver Asset/s.

HTTP Method

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

Input URL Examples

A single Driver Asset may be deleted:

https://api.catch-e.com/fm/driver/assets/

To Delete multiple Driver Assets:

https://api.catch-e.com/fm/driver/assets/

JSON Example for multiple Asset deletion

https://api.catch-e.com/fm/driver/assets/Use the driver_asset_id in the JSON body:[ "3196579721328459821", "3196579721328459822"]

(Successful) Output Example (sample)

A successful deletion will only return a Body Status '204 No Content'.

Error Codes

Example error output

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Not Found", "status": 404, "detail": "The specified driver asset does not exist"}

DeleteDriverLiabilities

Overview

Allows you to Delete a Driver Liability.

HTTP Method

Use the HTTP Method 'DELETE' 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 URL Examples

A single Driver Asset may be deleted:

https://api.catch-e.com/fm/driver/liabilities/

To Delete multiple Driver Assets:

https://api.catch-e.com/fm/driver/assets/

JSON Example for multiple Asset deletion

https://api.catch-e.com/fm/driver/assets/Use the driver_liability_id in the JSON body:[ "3196579721328459821", "3196579721328459822"]

(Successful) Output Example (sample)

A successful deletion will only return a Body Status '204 No Content'.

Error Codes

Example error output

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Not Found", "status": 404, "detail": "The specified driver liability does not exist"}