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

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

client_id

string

Client ID to add the driver to

Yes

given_name

string

Driver's given name

Yes

surname

string

Driver's surname

Yes

home_email

string

Driver's email address

Yes

Optional fields

string

Refer to the swagger documentation for the list of optional fields that can be passed

No

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

Response Details

Validation Message

Comments

201 Created

A successful response returns all fields in the new driver record

400 - Bad Request

The JSON payload content is not formatted correctly

401 - 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

You do not have permissions for this request

422 - Failed Validation

Validation failed - see error examples for specific issues

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