ChangeContractCostCentre

This method changes the contract's cost centre and creates a cost centre change event.

This works in the same way as creating a Contracts / Events Cost Centre Change.

Supplementary SWAGGER documentation is available here: https://api.catch-e.com/docs/#/Contract%20%2F%20Events/changeContractCostCentre

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 ContractEvents:changeContractCostCentre.

Note: This API can also be enabled for the following external roles: fleetmanager, groupmanager and package_employer. Contact your Account Manager if you would like to enable this permission for one of these roles.

HTTP Method

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

URL Examples

https://api.catch-e.com/fm/contract/events/{contract_id}/change-cost-centre

Parameters - Path Variables

Key	Format	Notes	Mandatory
contract_id	string	Target contract ID to edit	Yes

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_cost_centre_id	string	Pass the client's client_cost_centre_id	Yes
event_date	string (date)	Pass the effective date of the contract event. If no date is passed, the system date will be used. Format: YYYY-MM-DD or 0000-00-00 to leave blank	No
description	string	An event description. This will be ignored if there is an event_description_id or the event_description_id validation fails	No
allocation	decimal	Pass an allocation value out of 100. If not passed, defaults to 100.00	No
contract_event_action_id	string	Contract event action from available list. Use getContractEventActions API. If not passed, defaults to 100000 (None)	No
due_date	string (date)	Due date for the event. Format: YYYY-MM-DD	No
completed_flag	string	If not passed, respects default setting from Posting Classes / Details "Event Completed" field	No
override_warnings_flag	string	Pass as 'yes' to override warnings about invalid odometer readings. If not passed, defaults to 'no'	No

Input Fields (JSON)

{ "client_cost_centre_id": "100430", "event_date": "2024-03-01", "description": "API TEST 4 changeCostCentre", "allocation": "70.56", "contract_event_action_id": "100000", "due_date": "2024-03-01", "completed_flag": "yes", "override_warnings_flag": "yes" }

Response Details

Validation Message	Comments
201 Created	A successful response returns the newly created cost centre change event with all contract event fields
404 - Not Found	API endpoint not found
422 - Unprocessable Entity	Failed validation - see error examples for specific validation issues
403 - Forbidden	You do not have permissions for this request

Successful Response Example

{ "contract_event_id": "109980", "contract_id": "102888", "posting_class_id": "100032", "attachment_id": null, "event_date": "2024-03-01", "table_name": "fm_client_cost_centres", "record_id": "100430", "event_value": "MATT CC1", "description": "API TEST 4 changeCostCentre", "contract_event_value_id": null, "contract_event_description_id": "0", "contract_event_action_id": "100000", "due_date": "2024-03-01", "completed_flag": "yes", "event_amount": 70.56, "message_type": null, "user_id": "11244", "last_edit": "2024-06-25 01:27:39", "status_flag": "active" }

Error Response Examples

422 Unprocessable Entity - Invalid contract_id

{ "contract_id": { "noRecordFound": "No record matching the input was found" } }

The contract_id passed is not stored in the database. If the user is external, contracts that are not linked to the user's login will not be visible. The contract_id may be valid, but it is not visible to this user.

422 Unprocessable Entity - Invalid client_cost_centre_id (does not belong to contract's client)

{ "client_cost_centre_id": { "invalidValue": "Specified client cost centre does not belong to the client associated with the specified contract" } }

The client_cost_centre_id is stored in the database but does not belong to the linked client.

422 Unprocessable Entity - Invalid client_cost_centre_id (not found)

{ "client_cost_centre_id": { "noRecordFound": "No record matching the input was found" } }

The client_cost_centre_id is not stored in the database or is not available to the authenticated user.

422 Unprocessable Entity - Invalid event_date

{ "event_date": { "invalidDate": "The input does not appear to be a valid date" } }

You must enter a valid date as YYYY-MM-DD or 0000-00-00 to leave the event_date blank.

422 Unprocessable Entity - Invalid contract_event_description_id

{ "contract_event_description_id": { "noRecordFound": "No record matching the input was found" } }

The contract_event_description_id is not stored in the database.

422 Unprocessable Entity - Invalid allocation

{ "allocation": { "notBetween": "The input is not between '1' and '100', inclusively" } }

The allocation cannot be higher than 100 or lower than 0.

422 Unprocessable Entity - Invalid contract_event_action_id

{ "contract_event_action_id": { "noRecordFound": "No record matching the input was found" } }

The contract_event_action_id is not stored in the database.

422 Unprocessable Entity - Cost Centre already allocated

{ "warning_messages": { "client_cost_centre_id": { "costCentreAlreadyAllocated": "Specified client cost centre is already allocated to this contract" } } }

Cost Centre is already allocated to this contract.

403 Forbidden

{ "detail": "Forbidden" }

You do not have permissions for this request.

404 Not Found

{ "detail": "API endpoint not found" }