CreateDrivers
This method creates a driver or multiple drivers.
Supplementary SWAGGER documentation is available here: 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.
Audit history records can be created simultaneously. You will need permissions for Audit:UserIdOverride to enable this.
Note: Authenticate with the API before running this method.
HTTP Method
Use the HTTP Method 'POST' for consuming this web service.
URL Examples
https://api.catch-e.com/fm/drivers
Headers
Body (JSON)
Refer to supplementary SWAGGER documentation for complete list of optional fields: https://api.catch-e.com/docs/#/Drivers/createDrivers
Input Fields (JSON)
{ "client_id": "100002", "given_name": "Mary", "surname": "Hopkins", "home_email": "mary.hopkins@vic.com.au" } Duplicate Driver Warnings
Before a driver is created, the API checks the client's existing drivers for:
A duplicate name: another driver at the same client with the same given name and surname.
A duplicate employee number: another driver at the same client with the same employee number.
Names and employee numbers are matched regardless of upper or lower case, and leading or trailing spaces are ignored. Spaces inside a name are not removed.
A duplicate is returned as a warning rather than a hard refusal, because two different people can share a name. The request returns a 422 until it is resent with override_warnings_flag set to yes. Where both duplicates are found, both warnings are returned together.
Creating a list of drivers
Every driver in the list is checked against the client's existing drivers before any driver is created.
Drivers sent together in the same request are not compared with each other, so two new drivers with the same name or employee number in one list are both created.
If any driver has a warning and no override, nothing in the list is created. The response reports the first refused driver only, keyed by its position in the request, starting at 0.
Duplicate Driver Record refusal
The existing refusal for a driver with the same name, email address and client is unchanged and cannot be overridden. Without the override, it is returned together with the duplicate name warning. With the override, it is returned on its own. When creating a list, every driver this refusal stops is listed, and no warnings are added.
Creating a new driver as part of creating a quote is not affected by these warnings.
Response Details
Successful Response Example
{ "_links": { "self": { "href": "https://api.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, "ato_loan_flag": "no", "australian_resident": "yes", "card_account_number": "", "client_cost_centre_id": null, "client_id": "100002", "contact_note": null, "created": "2021-08-30 03:40:07", "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, "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, "insurance_broker_fee_exempt_flag": "yes", "kyc_verified_flag": "no", "landlord_name": "", "landlord_telephone": "", "last_edit": "2021-08-30 03:40:07", "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.catch-e.com/fm/drivers/101224" } } } ] }, "total_items": 1 } Error Response Examples
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" } 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 - Duplicate Driver Record
{ "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 the provided given name, surname, email address and client combination.
422 Failed Validation - Duplicate Driver Name (Warning)
{ "warning_messages": { "surname": { "duplicateDriverName": "Driver 'Alex Smith' already exists for Client 'Example Client Pty Ltd'" } }, "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unprocessable Entity", "status": 422, "detail": "Failed Validation" } A driver with the same given name and surname already exists for the client. Resend with override_warnings_flag set to yes to create the driver.
422 Failed Validation - Duplicate Employee Number (Warning)
[Example to be confirmed]
A driver with the same employee number already exists for the client. Resend with override_warnings_flag set to yes to create the driver.
422 Failed Validation - Duplicate Driver in a List (Warning)
{ "warning_messages": { "1": { "surname": { "duplicateDriverName": "Driver 'Alex Smith' already exists for Client 'Example Client Pty Ltd'" } } }, "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unprocessable Entity", "status": 422, "detail": "Failed Validation" } The second driver in the list (position 1) is a duplicate. No drivers in the list were created. Where the refused driver is the first in the list (position 0), warning_messages is returned as an array, the same way validation_messages is.
422 Failed Validation - Missing 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" } One or more mandatory fields are missing. All four mandatory fields (client_id, given_name, surname, home_email) must be included.
422 Failed Validation - Invalid client_id
{ "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.
Was this helpful?
More in Create & Modify Driver Endpoints
ChangeContractDriverCreateDriverBankAccountsGetDriverBankAccountsStill need help? Ask the team