createContractOdometer

This page contains content which will be released in the next deployment

Overview

Records an odometer reading against a contract.

This method requires the ContractMaintenance:Create permission to be associated with your role.

It performs the same function as the Odometer button on the Contracts / Maintenance screen. Each reading is saved as a maintenance record against the contract, and an audit record is written for it.

Declaration. Submitting a reading is treated as the declaration the Contracts / Maintenance screen asks of external users: that the date and odometer reading are accurate, true and correct.

• The reading is recorded against the authenticated user, with the date and time, in the maintenance record and the audit trail.

• To record it against the person who supplied the reading, send their user id in the Audit-User-Id header. This requires the Audit:UserIdOverride permission.

• If your application lets a person enter readings, show them this declaration before submitting.

Permissions

The permission for this api is stored in [gb_api_permissions]permission as 'ContractMaintenance:Create'.

Only roles with a stored link to this permission in [gb_role_api_permissions] can run this api.

• The permission is available to client roles with API access. To grant it, go to System / Roles, open your API role (for example, web_services), select the APIs tab and tick ContractMaintenance:Create.

• A newly ticked permission can take up to 5 minutes to take effect.

HTTP Method

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

URL Examples

https://api.demo.catch-e.com/fm/contract/{contract_id}/odometer https://api.{{environment}}.catch-e.com/fm/contract/{contract_id}/odometer https://api.test.catch-e.com/fm/contract/{contract_id}/odometer 

Input Fields (Header)

Path Parameters

Input Fields (JSON)

{ "odometer": 84250, "odometer_date": "2026-08-28", "description": "Service check-in reading", "override_warnings_flag": "no" } 

Any other field in the request body, including client_id and odometer_valid_flag, is rejected with a 422.

How the Reading Is Saved

• The reading is saved as an odometer record marked as valid.

• The client is taken from the contract.

• The record is stamped with the posted date, and recorded against the authenticated user, or the Audit-User-Id user if one is supplied.

• A reading can be added to a contract in any status.

Out-of-Range Readings

The reading is compared with the contract's estimated odometer at that date, using the tolerance configured for your system. If the contract has no earlier valid reading to estimate from, a range of 10,000 km either side is used instead.

• Within the expected range: the reading is saved.

• Outside the expected range, without override_warnings_flag = 'yes': the request returns a 422 with a warning, and nothing is saved.

• Outside the expected range, with override_warnings_flag = 'yes': the reading is saved.

Duplicate Readings

A reading with the same contract, date and odometer value as an existing reading is rejected. This also applies when the same reading is sent more than once at the same moment: only one is saved.

Response Details

Success

201 - Created

Returns the full maintenance record created. The fields below are illustrative.

{ "maintenance_id": "1047380", "contract_id": "104895", "client_id": "100001", "odometer": 84250, "odometer_date": "2026-08-28", "odometer_valid_flag": "valid", "status_flag": "history-only", "posted_date": "2026-10-19", "description": "Service check-in reading", "_links": { "self": { "href": "https://api.catch-e.loc/fm/contract/104895/odometer" } } } 

Error Response Details

422 Unprocessable Entity

{ "validation_messages": { "contract_id": { "recordNotFound": "Contract not recognised!" } }, "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unprocessable Entity", "status": 422, "detail": "Failed Validation" } 

{ "validation_messages": { "odometer": { "isEmpty": "You must enter a non-zero odometer reading!" } }, "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unprocessable Entity", "status": 422, "detail": "Failed Validation" } 

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

401 Unauthorized

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

403 Forbidden

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

406 Not Acceptable

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

415 Unsupported Media Type

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unsupported Media Type", "status": 415, "detail": "Not Acceptable" } 

500 Internal Error

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

default Unexpected Error

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