Insert New Contract Budgets

Beta Function

Allows insertion of a new contract budget period for a contract.

This API replicates the system process used to adjust lease period billing.

Permissions

Permission required:

• ContractBudgets:Insert

Only roles linked to this permission can execute the API.

Default access is provided to:

• web-services role

HTTP Method

POST

Endpoint

https://api.catch-e.com/fm/contract/budgets/insert

Input Fields (Headers)

Input Fields (Body)

Contract Identification

• contract_id (int) — required

Billing Controls

• billing_period (string) — required in some conditions

• billing_date (string)

• payment_method (string)

Budget Data

• budgets (string/object) — required

  • Uses posting class code

  • Missing class codes create zero-value budgets

Amounts

• amount_net (string) — required

• amount_gst (string) — optional

  • Defaults to 0 if not provided

  • Overrides GST flag if mismatched

Example Request

[ { "contract_id": 101066, "billing_period": 3, "payment_method": "direct-debit", "billing_date": "2014-11-08", "budgets": { "MFEE": { "amount_net": 200, "amount_gst": 20 } } }]

Successful Response

{ "affected_records": 2 }

Error Codes

422 Unprocessable Entity

• Contract suspended

• Missing contract start date

• Billing date before contract start

• Missing budget data

• Invalid budget code

• Invalid billing period format

423 Locked

• Contract is being edited or billing is processing

403 Forbidden

• Insufficient permissions

Error Example

{
 "validation_messages": [
 {
 "billing_period": {
 "notInt": "Invalid billing_period '3.1'. Must be whole number."
 }
 }
 ],
 "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
 "title": "Locked",
 "status": 423
}

Update Contract Budgets

Overview

Updates existing contract budget data.

This is equivalent to:

• Contract Lease Edit

• Contract Lease Vary

Permissions

• ContractBudgets:Update

Only roles with this permission can execute the API.

HTTP Method

POST

Endpoint

https://api.catch-e.com/fm/contract/budgets/update

Input Fields (Headers)

Input Fields (Body)

Contract Control

• contract_id (int) — required

• update_single_period (string yes/no)

Billing Control

• billing_period (string)

• billing_interval (string)

Budget Updates

• budgets (object)

  • posting class codes as keys

Payment Settings

• payment_method (string)

Example Request

{
 "contract_id": 100000,
 "payment_method": "direct-debit",
 "update_single_period": "no",
 "billing_period": 1,
 "budgets": {
 "F": {
 "amount_net": 50,
 "amount_gst": 5
 },
 "MAINT": {
 "amount_net": 75,
 "amount_gst": 7.5
 }
 }
}

Successful Response

{ "affected_records": 2 }

Error Codes

422 Unprocessable Entity

• Invalid contract ID

• Invalid billing period

• Invalid budget code

• Invalid payment method

• Invalid numeric formats

423 Locked

• Contract or billing process active

403 Forbidden

• No API permission

Error Example

{
 "warning_messages": {},
 "validation_messages": {},
 "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
 "title": "Unprocessable Entity",
 "status": 422
}

Perform Contract Funds Check

Overview

Returns contract fund values used in the Funds Check interface.

Used for:

• Reporting

• Export queries

• Scheduled reporting placeholders

Permissions

• SignonToken:Create

Accessible to:

• web-services role

HTTP Method

GET

Endpoint

https://api.catch-e.com/fm/contract/funds

Input Fields

Query Parameters

• contract_id (int) — required

Example Request

https://api.catch-e.com/fm/contract/funds?contract_id=100000

Successful Response

Returns budget breakdown including:

• Finance

• Maintenance

• Fuel

• Insurance

• Fees

• Other categories

Includes:

• budget

• actual

• variance

• available

• posting class codes

• balances

Error Response

{
 "warning_messages": {},
 "validation_messages": {},
 "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
 "title": "Unprocessable Entity",
 "status": 422,
 "detail": "Failed Validation"
}