getContractMaintenance

Overview

Retrieve a Contract's maintenance history — fm_maintenance records — as a standalone, read-only collection. Previously these rows were only reachable via approval-scoped lookups or indirectly through the maintenance import staging table; this method reads fm_maintenance directly.

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

Permissions

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

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

HTTP Method

Use the HTTP Method GET for consuming this web service.

URL Examples

https://api.demo.catch-e.com/fm/contract/maintenance 
https://api.{{environment}}.catch-e.com/fm/contract/maintenance?contract_id={contract_id} 
https://api.test.catch-e.com/fm/contract/maintenance?contract_id={contract_id}&client_id={client_id}

Query Parameters

Key	Format	Notes	Mandatory
contract_id	string	Filters to one contract.	No
posting_class_id	string	Filters by posting class.	No
client_id	string	Filters by client.	No
supplier_id	string	Filters by supplier.	No
invoice_no	string	Filters by invoice number.	No
page	integer	Defaults to `1` if omitted.	No
page_size	integer	Defaults to `25` if omitted.	No

All filters are combinable — results must match every supplied filter (AND semantics).

Response Details

Success

200 OK

{ "_links": { "self": { "href": "https://api.catch-e.loc/fm/contract/maintenance?contract_id=100000" } }, "_embedded": { "fm_maintenance": [] }, "page": 1, "page_size": 25, "total_items": 0, "page_count": 0 }

The specific field list for each fm_maintenance record wasn't defined in this ticket's acceptance criteria — leaving the embedded object generic here rather than inventing field names. Worth confirming the exact response schema against the implementation before publishing.

Records with status_flag = 'deleted' are never returned, regardless of any filter supplied.

Error Response Details

Validation Message	Comments
422 - Unprocessable Entity	An invalid filter value — a non-existent `contract_id`, `posting_class_id`, `client_id`, or `supplier_id`. The error names the specific offending field.

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

Validation Message	Comments
403 Forbidden	No authentication token was supplied, or you don't have the ContractMaintenance:Get permission. (The ticket's test cases specify 403 for the no-token case — note this differs from the more common convention of 401 for missing authentication; flagging for confirmation rather than silently correcting it.)

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

Validation Message	Comments
401 Unauthorized	1. You have not authenticated before running this API or 2. The token_timeout of the current session has passed. You need to authenticate again. (Note: the ticket's own test cases specify 403 for a missing token instead — see the row above. Both are included here since the AC is explicit about the 403 case, but 401 is the platform-standard response for this condition.)

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

Validation Message	Comments
406 Not Acceptable

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

Validation Message	Comments
415 Unsupported Media Type

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

Validation Message	Comments
500 Internal Error

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

Validation Message	Comments
default Unexpected Error

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