GetDrivers

Allows you to extract details for multiple drivers.

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

Note: Authenticate with the API before running this method.

HTTP Method

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

URL Examples

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

https://api.catch-e.com/fm/drivers?client_id=100052&given_name=%&surname=%&page=1&page_size=25

Parameters - Query String

Key	Format	Notes	Mandatory
client_id	string	Client ID	No
client_cost_centre_id	string	Client Cost Centre ID	No
given_name	string	Given name. This field supports the wildcard % operator (see Wildcard % operator notes below)	No
surname	string	Surname. This field supports the wildcard % operator (see Wildcard % operator notes below)	No
home_email	string	Email address. Must be valid format	No
external_code	string	External code. This field supports the wildcard % operator (see Wildcard % operator notes below)	No
user_id_package_advisor	string	Package advisor user ID	No
page	integer	Page number. Default value: 1	No
page_size	integer	Page size. Default value: 25	No

Wildcard % Operator Notes

If you are using the Postman app with the wildcard operator, search strings such as %ab% or %ba% will return an error response.

If you need to search %ab% or %ba%, use %25ab%25 or %25ba%25 as required to return results as expected.

Input Fields (JSON)

Example query parameters:

{ "client_id": "100052", "client_cost_centre_id": null, "external_code": "%", "given_name": "%", "surname": "%", "user_id_package_advisor": null, "page": "1", "page_size": "25" }

Response Details

Validation Message	Comments
200 OK	Successful response returns paginated list of drivers matching filter criteria
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
409 - Conflict	Invalid page number provided
422 - Unprocessable Entity	Invalid input data (e.g. invalid email format, email domain issues)

Successful Response Example

{ "_links": { "self": { "href": "https://api.catch-e.com/fm/drivers?client_id=100052&page=1&page_size=25" }, "first": { "href": "https://api.catch-e.com/fm/drivers?client_id=100052&page_size=25" }, "last": { "href": "https://api.catch-e.com/fm/drivers?client_id=100052&page=2&page_size=25" }, "next": { "href": "https://api.catch-e.com/fm/drivers?client_id=100052&page=2&page_size=25" } }, "_embedded": { "fm_drivers": [ { "driver_id": "101140", "given_name": "Kylie", "surname": "Lower", "home_email": "demo@catch-e.com.au", "client_id": "100209", "status_flag": "active", "_links": { "self": { "href": "https://api.catch-e.com/fm/drivers/101140" } } } ] }, "page_count": 2, "page_size": 25, "total_items": 34, "page": 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.

409 Conflict

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Conflict", "status": 409, "detail": "Invalid page provided" }

Invalid page number provided.

422 Unprocessable Entity - Invalid Email Format

{ "validation_messages": { "home_email": { "emailAddressInvalidFormat": "The input is not a valid email address. Use the basic format local-part@hostname" } } }

Invalid email address format.

422 Unprocessable Entity - Invalid Email Domain

{ "validation_messages": { "home_email": { "emailAddressInvalidHostname": "'catch-e'.com.au' is not a valid hostname for the email address", "hostnameInvalidHostnameSchema": "The input appears to be a DNS hostname but cannot match against hostname schema for TLD 'AU'", "hostnameInvalidLocalName": "The input does not appear to be a valid local network name" } } }

Email domain contains invalid characters (e.g. apostrophe) or does not conform to valid hostname schema.