patchApproval

patchApproval

Overview

This method updates an existing approval. It is a partial update (merge-patch): only the fields you supply are updated, and all other fields keep their current values.

This method is not idempotent. For a full replace of the approval, use updateApproval.

An fm_approvals table lock is obtained while this API runs.

This method requires the Approvals:Update permission to be associated with your role.

Permissions

The permission for this api is stored in [gb_api_permissions]permission as 'Approvals:Update'.

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

HTTP Method

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

URL Examples

https://api.demo.catch-e.com/fm/approvals/1234 https://api.{{environment}}.catch-e.com/fm/approvals/1234 https://api.test.catch-e.com/fm/approvals/1234

Input Fields (Header)

Key

Format

Notes

Mandatory

Delegated-Locking-Session-Id

string

(Optional) Locking responsibility will be delegated to the specified Session Id. The API will only verify that locks exist for this session id, and will not obtain them itself. Requires the DelegatedLocking permission.

No

Audit-User-Id

string

(Optional) User Id to use for audit purposes. Up to 5 digits. Requires the Audit:UserIdOverride permission.

No

Time-Zone

string

(Optional) Approvals will be processed in the specified timezone. Default UTC. Accepts a named time zone (e.g. 'Australia/Sydney') or an offset from UTC (e.g. '+10:00').

No

Path Parameters

Key

Format

Notes

Mandatory

approval_id

string

The Approval Id. A positive whole number, up to 10 digits, with no leading zeros.

Yes

Input Fields (JSON)

Supply only the fields you want to update. The fields are the same top-level fields used by updateApproval.

Key

Format

Notes

Mandatory

approval_limit

number (double)

Default 0.

No

approval_sub_status_id

string

No

attachment_id

string

No

bank_details_correct_flag

string

Allowed values: yes, no. Default no.

No

billing_period

integer (int32)

No

billing_period_item_no

integer (int32)

No

client_phone

string

No

contract_id

string

No

credit_note_flag

string

Allowed values: yes, no. Default no.

No

driver_aware_flag

string

Allowed values: yes, no. Default no.

No

driver_bank_account_id

string

No

driver_name

string

No

driver_phone

string

No

external_order_number

string

No

invoice_date

string (date)

No

invoice_no

string

No

misc_phone

string

No

notes

string

No

franchise_notes

string

No

odometer

integer (int32)

No

odometer_date

string (date)

No

odometer_valid_flag

string

Allowed values: valid, invalid, none.

No

payee_payment_method_id

string

No

reimbursement_flag

string

Allowed values: yes, no. Default no.

No

status_flag

string

Allowed values: active, batch, cancelled, rejected, requested.

No

supplier_contact

string

No

supplier_franchise_vehicle_id

string

No

supplier_id

string

No

supplier_phone

string

No

maintenance_lines

array

No

maintenance_lines[].maintenance_id

string

No

maintenance_lines[].job_number

integer (int32)

No

maintenance_lines[].posting_class_id

string

No

maintenance_lines[].vmrs_code_id

string

No

maintenance_lines[].work_code_id

string

No

maintenance_lines[].cause_code_id

string

No

maintenance_lines[].type

string

Allowed values: P, U.

No

maintenance_lines[].recharge_flag

string

Allowed values: Y, N.

No

maintenance_lines[].description

string

No

maintenance_lines[].quantity

number (double)

No

maintenance_lines[].retail_price

number (double)

No

maintenance_lines[].cost_price

number (double)

No

maintenance_lines[].gst_cost

number (double)

No

Example

{ "invoice_date": "2026-01-15", "invoice_no": "string", "notes": "string", "status_flag": "active" }

Response Details

Success

200 - OK

Returns the updated approval.

{ "_links": { "self": { "href": "https://api.catch-e.loc/fm/approvals/1234" } }, "approval_id": "1234", "contract_id": "1234", "user_id": "1234", "supplier_id": "1234", "supplier_franchise_vehicle_id": "1234", "supplier_contact": "string", "supplier_phone": "string", "payee_payment_method_id": "1234", "driver_bank_account_id": "1234", "driver_name": "string", "driver_phone": "string", "client_phone": "string", "misc_phone": "string", "notes": "string", "franchise_notes": "string", "invoice_no": "string", "invoice_date": "2026-01-15", "billing_period": 0, "reimbursement_flag": "no", "driver_aware_flag": "no", "odometer": 1, "odometer_date": "2026-01-15", "odometer_valid_flag": "no", "bank_details_correct_flag": "no", "attachment_id": "1234", "source": "internal", "external_order_number": "string", "approval_limit": 0, "created": "2026-01-15", "last_edit": "2026-01-15", "user_id_edit": "string", "posted_date": "2026-01-15", "credit_note_flag": "no", "approval_sub_status_id": "1234", "requested_audit_attempt_count": 1, "status_flag": "no", "maintenance_lines": [ { "maintenance_id": "1234", "job_number": 1, "posting_class_id": "1234", "vmrs_code_id": "1234", "work_code_id": "1234", "cause_code_id": "1234", "type": "P", "recharge_flag": "Y", "description": "string", "quantity": 100.0, "retail_price": 100.0, "cost_price": 100.0, "gst_cost": 100.0 } ] }

Error Response Details

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.

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

Validation Message

Comments

403 - Forbidden

- You do not have permissions for this request. - Go to System Roles and enter 'web_services' - Navigate to the Roles / APIs tab to make sure the permission you need to run this API is checked.

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

Validation Message

Comments

404 - Not Found

The approval does not exist.

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

Validation Message

Comments

406 - Not Acceptable

The Accept header of the request does not match a response format this API supports.

{ "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

The Content-Type of the request is not supported by this API.

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

Validation Message

Comments

422 - Unprocessable Entity

One or more input fields failed validation. The field name and message are returned in validation_messages.

{ "warning_messages": {}, "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" }

Validation Message

Comments

423 - Locked

The approval record is locked by another process or user. An fm_approvals table lock is obtained while this API runs.

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

Validation Message

Comments

424 - Failed Dependency

Lock expected. A Delegated-Locking-Session-Id was supplied, but the expected lock for that session was not found.

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

Validation Message

Comments

500 - Internal Error

An unexpected error occurred on the server.

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

Validation Message

Comments

default - Unexpected Error

Any other unexpected error.

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