createContractEvents

createContractEvents

Overview

This method creates contract events, mirroring the functionality of creating new event records within the system. For storing attachments to newly created events, follow up with the "Save an attachment" API.

Each contract event can now optionally be assigned to a specific user via the new user_id field, rather than always defaulting to the authenticated caller. This is the owner/assigned user of the event and is functionally distinct from the audit trail — who actually submitted the request is still recorded independently, regardless of the user_id supplied.

This method requires the ContractEvents:Create permission to be associated with your role.

Permissions

The permission for this api is stored in [gb_api_permissions]permission as 'ContractEvents:Create'.

Only roles with a stored link to this permission in [gb_role_api_permissions] can run this api. No additional permission is required to assign an event to a different user — any caller with ContractEvents:Create can set user_id to any valid user.

HTTP Method

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

URL Examples

https://api.demo.catch-e.com/contract-events
https://api.{environment}.catch-e.com/contract-events
https://api.test.catch-e.com/contract-events

Input Fields (JSON)

Submit an array containing one or more contract event objects.

[  {    "contract_id": "string",    "posting_class_id": "string",    "event_date": "2026-08-19",    "contract_event_value_id": "string",    "event_value": "string",    "contract_event_description_id": "string",    "description": "string",    "event_amount": 0,    "contract_event_action_id": "string",    "due_date": "2026-08-19",    "completed_flag": "no",    "attachment_id": "string",    "status_flag": "active",    "user_id": "100000"  }]

Field

Type

Required

Details

contract_id

string (numeric)

Yes

Associated contract

posting_class_id

string (numeric)

Yes

Identifies posting class

event_date

string (YYYY-MM-DD)

Yes

Applicable date

contract_event_value_id

string (numeric)

Conditional

May be required depending on posting class

event_value

string

Yes

Event description/label

contract_event_description_id

string/null

No

Optional description reference

description

string

No

Free-text details

event_amount

number

Yes

Monetary value

contract_event_action_id

string (numeric)

Yes

Associated action identifier

due_date

string (YYYY-MM-DD)

No

Due date for the event

completed_flag

string

Yes

"yes" or "no"

attachment_id

string (numeric)

No

Associated attachment reference

status_flag

string

Yes

E.g., "active"

user_id

string

No

(Optional) gb_users.user_id to assign the event to. Must reference an existing user. When omitted, explicitly set to null, or submitted as an empty string, the event defaults to the authenticated (audit) user — this preserves existing behaviour.

Response Details

Success

201 - Created

All events in the batch are created in a single transaction, and only once every event has passed validation. The response contains every created record from the batch.

{
  "_links": { "self": { "href": "https://api.catch-e.loc/contract-events" } },
  "_embedded": {
    "contract_events": []
  }
}

Error Response Details

Validation Message

Comments

422 - Unprocessable Entity

user_id does not reference an existing record in gb_users. The request is rejected at validation — no events in the batch are created.

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

Validation Message

Comments

422 - Unprocessable Entity

Any other validation failure (e.g. a missing required field, a value outside the allowed range). Validation failure causes complete batch rollback — no records persist.

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

Note: This endpoint will never return the following error, regardless of batch size or failure cause:

{
  "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "Must call beginTransaction() before you can rollback"
}

401 Unauthorized

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

403 Forbidden

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

406 Not Acceptable

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

415 Unsupported Media Type

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

500 Internal Error

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

default Unexpected Error

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