Skip to content
/
Update an existing engage...

Update an existing engagement

Request

Update an existing engagement by ID

Partially updates an engagement. Only the fields included in the request body are modified — omitted fields are left unchanged. At least one field must be provided.

Updatable Fields:

  • Core engagement data (client, fiscal year, partner/manager staff, contacts, start/end dates, billing contact, CC staff, name template)
  • Engagement letter template and document template
  • Additional clients assigned to the engagement (full replace when provided)
  • Linked jobs/projects (full replace when provided)

Validation:

  • The engagement must exist (404 if not found)
  • The engagement must be in DRAFT or UNDER_REVISION status (400 otherwise)
  • All provided IDs (additional client IDs, job IDs, etc.) must reference valid records
  • At least one field must be provided (400 if request body is empty)

Replace behavior: When additionalClientIds or jobIds is provided, it fully replaces the existing associations — it is not additive. When jobIds is provided without additionalClientIds, the existing additional clients are preserved.

Note: Nullable fields (e.g. secondaryContactId, endDate) cannot be explicitly cleared to null via this endpoint — omitting them leaves the existing value unchanged.

Real Example:

curl --location --request PATCH 'https://{{host}}/api/v1/engagements/12345' \
--header 'Authorization: bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
  "fiscalYear": 2025,
  "partnerStaffId": 456,
  "additionalClientIds": [789, 790]
}'

Response Example:

{
  "id": 12345
}
Security
BearerAuth
Path
engagementIdinteger, (int64), >= 1required

Unique identifier of the engagement to update

Example:12345
Bodyapplication/jsonrequired
clientIdinteger or null, (int64)

ID of the primary client for this engagement

Example:789
fiscalYearinteger or null, (int32)

Fiscal year of the engagement

Example:2025
partnerStaffIdinteger or null, (int64)

ID of the partner staff member assigned to the engagement

Example:456
managerStaffIdinteger or null, (int64)

ID of the manager staff member assigned to the engagement

Example:457
primaryContactIdinteger or null, (int64)

ID of the primary contact for this engagement

Example:101
secondaryContactIdinteger or null, (int64)

ID of the secondary contact for this engagement

Example:102
startDatestring or null, (date)

Engagement start date (YYYY-MM-DD)

Example:"2025-01-01"
endDatestring or null, (date)

Engagement end date (YYYY-MM-DD)

Example:"2025-12-31"
billingContactIdinteger or null, (int64)

ID of the billing contact for this engagement

Example:103
ccStaffIdsArray of integers or null, (int64)

IDs of staff members to CC on engagement communications

Example:
[
  458,
  459
]
engagementLetterTemplateIdinteger or null, (int64)

ID of the engagement letter template to use

Example:55
documentTemplateIdinteger or null, (int64)

ID of the document template to use

Example:66
engagementNameTemplatestring or null

Template string used to generate the engagement name

Example:"{clientName} {fiscalYear} Audit"
additionalClientIdsArray of integers or null, (int64)

IDs of additional clients to associate with this engagement. When provided, replaces all existing additional client associations.

Example:
[
  790,
  791
]
jobIdsArray of integers or null, (int64)

IDs of jobs (projects) to link to this engagement. When provided, replaces all existing job links. If additionalClientIds is omitted when jobIds is provided, existing additional clients are preserved.

Example:
[
  101,
  102
]
curl -i -X PATCH \
  https://api.doc.aiwyn.ai/_mock/bundle/api/v1/engagements/12345 \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "clientId": 789,
    "fiscalYear": 2025,
    "partnerStaffId": 456,
    "managerStaffId": 457,
    "primaryContactId": 101,
    "secondaryContactId": 102,
    "startDate": "2025-01-01",
    "endDate": "2025-12-31",
    "billingContactId": 103,
    "ccStaffIds": [
      458,
      459
    ],
    "engagementLetterTemplateId": 55,
    "documentTemplateId": 66,
    "engagementNameTemplate": "{clientName} {fiscalYear} Audit",
    "additionalClientIds": [
      790,
      791
    ],
    "jobIds": [
      101,
      102
    ]
  }'

Responses

Engagement updated successfully

Bodyapplication/json
idinteger, (int64)

ID of the updated engagement

Example:12345
Response
{
  "id": 12345
}