Employee / Claims

Auto-build claims

Use this method to build approvals for Salary Packaged contracts when funds are available. A claim is created for each item where there is a surplus between the contract's posted receipts total and posted actual costs total (the GST inclusive Total of all posted Payments, Claims and Approvals). This method requires the EmployeeClaims:Create permission to be associated with your role.

POST

/sp/approvals/auto-build-claims

Auto-build claims

curl --request POST \
  --url https://api.catch-e.com/sp/approvals/auto-build-claims \
  --header 'Authorization: <api-key>' \
  --header 'Audit-User-Id: <string>' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'build_only=no&client_id=%3Cstring%3E&disbursement_date=2023-12-25&pay_cycle_id=%3Cstring%3E&pay_run_id=%3Cstring%3E&posting_class_id=%3Cstring%3E&timezone=UTC'

{
  "_links": {
    "self": {
      "href": "https://api.catch-e.com/sp/approvals/auto-build-claims"
    }
  },
  "exceptions": {
    "123456": [
      "Substantiation event does not have an attachment"
    ],
    "123457": [
      "Substantiation event 'Completed Flag' is not checked"
    ],
    "123458": [
      "Substantiation event required"
    ],
    "123459": [
      "Substantiation event does not have an attachment",
      "Substantiation event 'Completed Flag' is not checked",
      "Latest substantiation event due date is less than report run date",
      "Total of Payments and Claims made with in the FBT year greater than specified event amount"
    ]
  },
  "processed_contracts": [
    100000,
    100001,
    100002
  ]
}

Authorizations

Authorizationstringheaderrequired

For accessing the API a valid token must be passed in all the queries in the 'Authorization' header.

A valid token is generated by the API and returned by the /authenticate method by supplying a valid username and password.

The following syntax must be used in the 'Authorization' header :

Bearer aaaaaa/bbbbbb.ccccccc.dddddd

Headers

Audit-User-Idstringheader

(Optional) User Id to use for audit purposes. This header requires the Audit:UserIdOverride permission to be associated with your role.

Maximum string length: 5

Pattern: ^[1-9]{1}[0-9]*$

Body

build_onlyenum<string>default:no

Build-only mode. When yes, claims are created at pending with the pending-funds sub-status and the run stops before posting (no batch post). When no (default), the run builds and posts as before.

Available options: yes, no

client_idstring

Client Id

Maximum string length: 10

Pattern: ^[1-9]{1}[0-9]*$

disbursement_datestring

Single date in ISO format Y-m-d (e.g. 2026-07-21). Restricts the build to contracts linked to a regular pay run whose effective disbursement date (COALESCE(disbursement_date, billing_date)) equals this date. Ad-hoc pay runs are excluded.

Maximum string length: 10

pay_cycle_idstring

Pay Cycle Id

Maximum string length: 10

Pattern: ^[1-9]{1}[0-9]*$

pay_run_idstring

Pay Run Id. Restricts the build to contracts linked to this pay run (that is, contracts sharing the pay run's client and pay cycle).

Only regular pay runs are supported: an ad-hoc or non-existent pay_run_id is rejected with 422.

Takes precedence over disbursement_date and over any supplied client_id / pay_cycle_id.

A blank value is treated as not supplied. If a scope field is supplied but neither pay_run_id nor disbursement_date resolves to a usable value, the request is rejected with 422.

posting_class_idstring

Posting Class Id.

Required in build-and-post mode. Optional in build-only mode (build_only = yes), where it defaults from the auto_build_claims_class_default global control (resolved code to id). If no value is supplied and no control is configured, or the resolved class is not configured as an expense-approval class, a 422 is returned.

Maximum string length: 10

timezonestringdefault:UTC

Claims will be raised in the specified timezone.

The timezone value can be given in several formats, none of which are case sensitive:

As a named time zone, such as 'Europe/Helsinki', 'US/Eastern', or 'MET'.
As a string indicating an offset from UTC of the form [H]H:MM, prefixed with a + or -, such as '+10:00', '-6:00', or '+05:30'. A leading zero can optionally be used for hours values less than 10;

Maximum string length: 100

Pattern: ^[a-zA-Z0-9\/\:\+\-\_]+$

Response

Success

_linksobject

exceptionsobject

processed_contractsstring[]

Still need help? Ask the team