Contracts API: GetContractEventActions

API endpoints for contract management

GetContractEventActions

This method returns a list of contract event actions.

Use this information to find and populate the required action for events in the API createContractEvents.

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

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 ContractEventActions:Get

Note: This API is not configured for external use.
Contact your Account Manager to discuss access to this API.

HTTP Method

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

URL Examples

https://api.demo.catch-e.com/authenticate
https://api..catch-e.com/authenticate
https://api.test.catch-e.com/fm/contract-event-actions

Parameters - Path Variables

KeyFormatNotesMandatory
namestringName of Action. This field supports the wildcard % operator (See Wildcard % operator notes below).No
pageinteger($int32)Page number. Default value : 1No
page_sizeinteger($int32)Page size. Default value : 25No

Wildcard % operator notes:

If you are using "Postman" app, with the wildcard operator, the search string of either %ab% or %ba%, will give this response:

"field_name": {"isEmpty": "Value is required and can't be empty"}.

If you need to search either %ab% or %ba%, please use %25ab%25 or %25ba%25 as required to return results as expected.

Successful Response Example

{ "_links": { "self": { "href": "https://api.test.catch-e.com/fm/contract-event-actions/?name=%25&page=1&page_size=25" }, "first": { "href": "https://api.test.catch-e.com/fm/contract-event-actions/?name=%25&page_size=25" }, "last": { "href": "https://api.test.catch-e.com/fm/contract-event-actions/?name=%25&page=1&page_size=25" } }, "_embedded": { "fm_contract_event_actions": [ { "contract_event_action_id": 100000, "name": "none", "_links": { "self": { "href": "https://api.test.catch-e.com/fm/contract-event-actions/100000" } } }, { "contract_event_action_id": 100001, "name": "closed", "_links": { "self": { "href": "https://api.test.catch-e.com/fm/contract-event-actions/100001" } } }, { "contract_event_action_id": 100002, "name": "urgent", "_links": { "self": { "href": "https://api.test.catch-e.com/fm/contract-event-actions/100002" } } }, { "contract_event_action_id": 100003, "name": "follow-up", "_links": { "self": { "href": "https://api.test.catch-e.com/fm/contract-event-actions/100003" } } } ] }, "page_count": 1, "page_size": 25, "total_items": 4, "page": 1}

Error Response Details

Validation MessagesComments
404 Not Found
"detail": "API endpoint not found"
422 Unprocessable Entity
{"name":{"noRecordFound": "No record matching the input was found"}}

| The name passed is not stored in the database. |
| 423 Failed Validation | |
| "detail": "Locked" | Either the Contract is being edited or Billing is being processed. Try again once the Contract is no longer in use or the Billing process has completed. |
| 403 - Forbidden | |
| "detail": "Forbidden" | You do not have permissions for this request. |

GetContractEventDescriptions

This method returns a list of contract event descriptions.

Use this information to find and populate the required description for events in the API createContractEvents.

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

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 ContractEventDescriptions:Get

Note: This API is not configured for external use.
Contact your Account Manager to discuss access to this API.

HTTP Method

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

URL Examples

https://api.demo.catch-e.com/authenticate
https://api..catch-e.com/authenticate
https://api.test.catch-e.com/fm/contract-event-descriptions

Parameters - Path Variables

KeyFormatNotesMandatory
postingclassidstringpostingclassid.Yes
includeinactiveflagstringAvailable values : no, yes Default value : noNo
pageinteger($int32)Page number. Default value : 1No
page_sizeinteger($int32)Page size. Default value : 25No

Successful Response Example

{ "_links": { "self": { "href": "https://api.test.catch-e.com/fm/contract-event-descriptions/?posting_class_id=100032&include_inactive_flag=no&page=1&page_size=25" }, "first": { "href": "https://api.test.catch-e.com/fm/contract-event-descriptions/?posting_class_id=100032&include_inactive_flag=no&page_size=25" }, "last": { "href": "https://api.test.catch-e.com/fm/contract-event-descriptions/?posting_class_id=100032&include_inactive_flag=no&page=1&page_size=25" } }, "_embedded": { "fm_contract_event_descriptions": [ { "contract_event_description_id": 100002, "posting_class_id": 100032, "event_description": "CC Description 1", "default_flag": "yes", "status_flag": "active", "_links": { "self": { "href": "https://api.test.catch-e.com/fm/contract-event-descriptions/100002" } } }, { "contract_event_description_id": 100003, "posting_class_id": 100032, "event_description": "CC Description 2", "default_flag": "no", "status_flag": "active", "_links": { "self": { "href": "https://api.test.catch-e.com/fm/contract-event-descriptions/100003" } } } ] }, "page_count": 1, "page_size": 25, "total_items": 2, "page": 1}

Error Response Details

Validation MessagesComments
404 Not Found
"detail": "API endpoint not found"
422 Unprocessable Entity
{"name":{"noRecordFound": "No record matching the input was found"}}

| The name passed is not stored in the database. |
| 423 Failed Validation | |
| "detail": "Locked" | Either the Contract is being edited or Billing is being processed. Try again once the Contract is no longer in use or the Billing process has completed. |
| 403 - Forbidden | |
| "detail": "Forbidden" | You do not have permissions for this request. |

GetContractEventValues

This method returns a list of contract event values.

Use this information to find and populate the required value for events in the API createContractEvents.

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

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 ContractEventValues:Get

Note: This API is not configured for external use.
Contact your Account Manager to discuss access to this API.

HTTP Method

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

URL Examples

https://api.demo.catch-e.com/authenticate
https://api..catch-e.com/authenticate
https://api.test.catch-e.com/fm/contract-event-values

Parameters - Path Variables

KeyFormatNotesMandatory
postingclassidstringpostingclassid.Yes
includeinactiveflagstringAvailable values : no, yes Default value : noNo
pageinteger($int32)Page number. Default value : 1No
page_sizeinteger($int32)Page size. Default value : 25No

Successful Response Example

{ "_links": { "self": { "href": "https://api.test.catch-e.com/fm/contract-event-values/?posting_class_id=100038&include_inactive_flag=no&page=1&page_size=25" }, "first": { "href": "https://api.test.catch-e.com/fm/contract-event-values/?posting_class_id=100038&include_inactive_flag=no&page_size=25" }, "last": { "href": "https://api.test.catch-e.com/fm/contract-event-values/?posting_class_id=100038&include_inactive_flag=no&page=1&page_size=25" } }, "_embedded": { "fm_contract_event_values": [ { "contract_event_value_id": 100000, "posting_class_id": 100038, "event_value": "eventValueOne", "default_flag": "no", "status_flag": "active", "_links": { "self": { "href": "https://api.test.catch-e.com/fm/contract-event-values/100000" } } } ] }, "page_count": 1, "page_size": 25, "total_items": 1, "page": 1}

Error Response Details

Validation MessagesComments
404 Not Found
"detail": "API endpoint not found"
422 Unprocessable Entity
{"posting_class_id":{"noRecordFound": "No record matching the input was found"}}

| The name passed is not stored in the database. |
| 423 Failed Validation | |
| "detail": "Locked" | Either the Contract is being edited or Billing is being processed. Try again once the Contract is no longer in use or the Billing process has completed. |
| 403 - Forbidden | |
| "detail": "Forbidden" | You do not have permissions for this request. |

Add Contract ID

Qualifiers

  1. Your system has been set-up with car benefit contracts
  2. An employee would like to package a Novated Lease or an Associate Lease
  3. You have created a vehicle quote for this
  4. You have accepted the vehicle quote

Create the item record

  1. Navigate to Employees / Item
  2. Pay Cycle - must be the same as the quote's pay cycle.
  3. Click on **
  4. Package Item - select a package item for a car benefit (I.e. Novated Lease, Associate Lease)
  5. Car Details
  6. Quote ID - may already be populated. If not it will populate automatically when the contract is added.
  7. Contract ID - enter or lookup the Contract ID of the vehicle contract
  8. Click on **

CreateEventSubscription

This method is used to register a webhook (HTTPS callback URL) to receive notifications for one or more event types.

When an event matching one of the subscribed types is emitted via the emitEvent endpoint, the system will automatically forward the event as a JSON HTTP POST request to the provided URL.

On event dispatch, the callback URL will receive an HTTP POST payload with the following structure:

"messageId": (A unique Message Id GUID - example "367326e8-a25c-5704-8146-46250ac8fd68"),
"timestamp": (ATOM date/time - example "2025-02-02T01:23:45.901Z"),
"clientId": (Client Id - example "demo")
"userId": (User Id - example "10000")
"environment": (API environment - example "test")
"eventType": (Event type - example "ping")
"subscriptionId": (Subscription Id responsible for event dispatch)
"signingCertURL": (Signing public certificate - used to verify x-payload-signature header),
"message": (The payload JSON),

Included in this response is the subscriptionId which can be used in the API deleteEventSubscription.

Supplementary SWAGGER documentation is available here: https://api.test.catch-e.com/docs/?/Events/createEventSubscription(https://api.test.catch-e.com/docs/?urls.primaryName=Main#/Events/createEventSubscription|).

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 Events:Subscribe

Note: This API is not configured for external use.
Contact your Account Manager to discuss access to this API.

HTTP Method

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

URL Examples

https://api.demo.catch-e.com/authenticate
https://api..catch-e.com/authenticate
https://api.test.catch-e.com/event/subscripton

Parameters - Path Variables

KeyFormatNotesMandatory
typesstringA list of event types the client wishes to subscribe to. The callback URL will be subscribed to all specified types.Yes
sourceSubscriptionIdstringAn optional source subscription id filter and in most cases will not need to be defined. This is only applicable when subscribing to event subscriber processing events.No
descriptionstringAn optional description of the subscription callback's purpose. This is useful for identifying the associated systems or processes that consume events from the subscription.No
callBackUrlstring($uri)The publicly accessible HTTPS endpoint to receive event notifications. Must support POST requests.Yes
callBackParametersdescriptionAdditional parameters to be included in the message payload supplied to the callback.No

Headers

KeyFormatNotesMandatory
Audit-User-IdstringPass 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:UserIdOverrideNo

Body Sample

Create an Event Subscription

[ { "types": [ "receipts.batch.posted" ], "sourceSubscriptionId": "14729133173082437332", "description": "Run autoBuildClaims when a receipt batch is posted", "callbackUrl": "https://api.test.catch-e.com/event/job/sp/approvals/auto-build-claims", "callbackParameters": { "additionalProp1": {} }}]

Response Details

Validation MessagesComments
202 OK
{ { "subscriptionId": "14729133173082439740" }}

| Subscription created. |
| 401 - Unauthorized | | |

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

| You have not authenticated before running this API or The token_timeout of the current session has passed. You need to authenticate again. |
| 403 - Forbidden | | |

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Forbidden", "status": 403, "detail": "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. |

DeleteEventSubscription

This is a restricted API.

This method is used to unsubscribe from all the registered event types.

Supplementary SWAGGER documentation is available here: https://api.test.catch-e.com/docs/?/Events/deleteEventSubscription(https://api.test.catch-e.com/docs/?urls.primaryName=Main#/Events/deleteEventSubscription|).

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 Events:Subscribe

Note: This API is not configured for external use.
Contact your Account Manager to discuss access to this API.

HTTP Method

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

URL Examples

https://api.demo.catch-e.com/authenticate
https://api..catch-e.com/authenticate
https://api.test.catch-e.com/event/subscription/{id}

Parameters - Path Variables

KeyFormatNotesMandatory
idstringId of the subscription to remove.Yes

Headers

KeyFormatNotesMandatory
Audit-User-IdstringPass 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:UserIdOverrideNo

Body Sample

Delete an Event Subscription

[ { "subscriptionId": "14729133173082439742" }]

Response Details

Validation MessagesComments
204 OK
Subscription deleted
401 - Unauthorized
{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unauthorized", "status": 401, "detail": "Unauthorized"}

| You have not authenticated before running this API or The token_timeout of the current session has passed. You need to authenticate again. |
| 403 - Forbidden | | |

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Forbidden", "status": 403, "detail": "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. |
| 422 - Unprocessable Entity | | |

{ "validation_messages": { "id": { "noRecordFound": "No record matching the input was found" } }, "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unprocessable Entity", "status": 422, "detail": "Failed Validation"}

| Invalid subscriptionId has been entered |