UpdateQuery

UpdateQuery

Update existing query stored in gb_queries table.

Requires Queries:Update permission.

Go to Roles / APIs and check on Queries:Update.

Queries validated prior to being saved.

HTTP Method

PUT

URL Examples

https://api.catch-e.com/gb/queries/{query_id}

Headers

Key

Format

Notes

Mandatory

Audit-User-Id

string

Pass user_id to create audit records. Only if authenticated user has Audit:UserIdOverride permission.

No

Body (JSON)

{ "name": "COUNT of contracts with Rego", "description": "Count of Active Contracts with Rego", "query": "SELECT COUNT(*) FROM fm_contracts WHERE suspend_date = '0000-00-00' AND reg_no != 'ORDER';", "super_flag": "no", "status_flag": "active" }

Successful Output

{ "query": "SELECT COUNT(*) FROM fm_contracts WHERE suspend_date = '0000-00-00' AND reg_no != 'ORDER';", "query_id": "100249", "name": "COUNT of contracts with Rego", "description": "Count of Active Contracts with Rego", "super_flag": "no", "max_execution_time": 300, "user_id_last_edit": "10937", "last_edit": "2023-12-05 10:47:53", "status_flag": "active", "_links": { "self": { "href": "https://api.catch-e.com/gb/queries/100249" } }, "_embedded": { "scheduler_jobs": [] } }

Response - 401 Unauthorized

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

You have not authenticated or token_timeout has passed. Authenticate again.

Response - 403 Forbidden

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

You do not have permissions. Go to System Roles, enter 'web_services', navigate to Roles / APIs and check permissions.

Response - 422 Unprocessable Entity

{ "warning_messages": { "fieldName": { "warningExceptionCode": "A textual description of the warning exception" } }, "validation_messages": { "fieldName": { "validationExceptionCode": "A textual description of the validation exception" } }, "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unprocessable Entity", "status": 422, "detail": "Failed Validation" }

Correct request content before resubmitting.

Response - 429 Too Many Requests

Rate limit exceeded. Response contains seconds to wait before retry. Rate limit includes all legacy web services and APIs. Whitelisted IP addresses excluded (includes localhost). Catch-e uses sliding window rate limiting.

Reference: https://blog.cloudflare.com/counting-things-a-lot-of-different-things/

Response - 500 Unexpected Error

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

Temporary outage or bug. If consistent, raise ticket with Account Manager. Supply complete Request & Response payloads.

Warning: Never send user login credentials in tickets. Catch-e staff have own credentials for debugging.

GetArchiveQueries

Get history of query changes for query stored in gb_queries table.

Requires Queries:Get permission.

Go to Roles / APIs and check on Queries:Get.

HTTP Method

GET

URL Examples

https://api.catch-e.com/gb/queries/archive

Parameters

Name

Format

Notes

Mandatory

query_id

string

Query ID

Yes

page

number

Page number (default: 1). Returns all pages by default.

No

page_size

number

Results per page (default: 25)

No

Successful Output

Example response shows three changes to Query ID 100249 using updateQuery.

{ "_links": { "self": { "href": "https://api.catch-e.com/gb/queries/archive?query_id=100249&page=1&page_size=25" }, "first": { "href": "https://api.catch-e.com/gb/queries/archive?query_id=100249&page_size=25" }, "last": { "href": "https://api.catch-e.com/gb/queries/archive?query_id=100249&page=1&page_size=25" } }, "_embedded": { "archived_queries": [ { "query_archive_id": "11989979731563965186", "query_id": 100249, "data_sha": "3f5f9c679ff38f9fd7ed5f6f649df9ac208a7cb0", "query": "SELECT COUNT(contract_id) AS contract_count FROM fm_contracts WHERE suspend_date = '0000-00-00' AND reg_no != 'ORDER' LIMIT 20;", "last_edit": "2023-12-05 10:46:16", "user_id_last_edit": 10000, "_links": { "self": { "href": "https://api.catch-e.com/gb/queries/archive" } } }, { "query_archive_id": "11989979731563965187", "query_id": 100249, "data_sha": "3403ad86b7a842f5079f772b16526fe76e2b9b70", "query": "SELECT COUNT(*) FROM fm_contracts WHERE suspend_date = '0000-00-00' AND reg_no = 'ORDER';", "last_edit": "2023-12-05 10:47:53", "user_id_last_edit": 10000, "_links": { "self": { "href": "https://api.catch-e.com/gb/queries/archive" } } }, { "query_archive_id": "11989979731563965206", "query_id": 100249, "data_sha": "6d4764ce4e5493ba59704b566c7bc592a9620f81", "query": "SELECT COUNT(*) FROM fm_contracts WHERE suspend_date = '0000-00-00' AND reg_no != 'ORDER';", "last_edit": "2023-12-05 11:01:18", "user_id_last_edit": 10000, "_links": { "self": { "href": "https://api.catch-e.com/gb/queries/archive" } } } ] }, "page_count": 1, "page_size": 25, "total_items": 3, "page": 1 }

Response - 401 Unauthorized

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

You have not authenticated or token_timeout has passed. Authenticate again.

Response - 403 Forbidden

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

You do not have permissions. Go to System Roles, enter 'web_services', navigate to Roles / APIs and check permissions.

Response - 422 Unprocessable Entity

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

Correct request content before resubmitting.

Response - 429 Too Many Requests

Rate limit exceeded. Response contains seconds to wait before retry. Rate limit includes all legacy web services and APIs. Whitelisted IP addresses excluded (includes localhost). Catch-e uses sliding window rate limiting.

Reference: https://blog.cloudflare.com/counting-things-a-lot-of-different-things/

Response - 500 Unexpected Error

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

Temporary outage or bug. If consistent, raise ticket with Account Manager. Supply complete Request & Response payloads.

Warning: Never send user login credentials in tickets. Catch-e staff have own credentials for debugging.

ExecuteReportWebService

Run selected system reports available from Fleet / Administration / Reports menu.

Supplementary SWAGGER documentation: api.catch-e.com/docs/#/Web%20Services/executeReportWebService

Available Reports

  • Accidents

  • Reg Renewals

  • Service Overdue

For setup requirements, refer to specific report documentation.

PrintQuery

Execute query stored in gb_queries table.

Requires Queries:Print permission.

Go to Roles / APIs and check on Queries:Print.

HTTP Method

GET

URL Examples

https://api.catch-e.com/gb/queries/print-query/{query_id}

Input - Headers

Representational output format controlled by HTTP Accept header. Three content types supported:

  • text/csv

  • text/xml

  • application/json (default)

Note: Queries that run successfully but result in 0 rows return HTTP 204 (No Content). Queries exceeding maximum_execution_time return HTTP 422 (Unprocessable Content).

Successful Output

Returns content based on selected query.

[ { "contract_count": "1142" } ]

Response - 401 Unauthorized

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

You have not authenticated or token_timeout has passed. Authenticate again.

Response - 403 Forbidden

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

You do not have permissions. Go to System Roles, enter 'web_services', navigate to Roles / APIs and check permissions.

Response - 422 Unprocessable Entity

Query not found:

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

Correct request content before resubmitting.

Execution timeout:

{ "validation_messages": { "query_id": { "invalidQuery": "Query execution was interrupted, maximum statement execution time exceeded." } } }

Query exceeded maximum_execution_time.

Response - 429 Too Many Requests

Rate limit exceeded. Response contains seconds to wait before retry. Rate limit includes all legacy web services and APIs. Whitelisted IP addresses excluded (includes localhost). Catch-e uses sliding window rate limiting.

Reference: https://blog.cloudflare.com/counting-things-a-lot-of-different-things/

Response - 500 Unexpected Error

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

Temporary outage or bug. If consistent, raise ticket with Account Manager. Supply complete Request & Response payloads.

Warning: Never send user login credentials in tickets. Catch-e staff have own credentials for debugging.