Create Engagements - AuditDashboard Developer Portal

Creates one or more new engagements.

Required fields: CompanyID and Title are always required. Period, Year, FieldworkStartDate,
and FieldworkEndDate are required only when your portal is set to require them (Settings > Field
Customization); if a field isn't marked required, you can leave it blank.
DivisionID is required if your portal has more than one division; if it only has one, we use that division automatically.

OwnerID is left unset if you omit it — the engagement is created with no owner. Being the
owner does not add you to the engagement's team — to include yourself or the owner as a
professional user, put that user id in ProfessionalUsers. The people in ProfessionalUsers
and ClientUsers are the only ones added. RoleID 0 assigns the default engagement role
(Request Administrator for firm, General for client); inherited administrators get no role row.

Status: only Draft (0) and InProgress (10) are accepted. Anything else (including Complete
and Reopened) is treated as Draft. To move an engagement to another status after it's created,
use the PATCH status endpoints.

AddToSchedule: when true, the new engagement is added to the schedule (an active engagement
schedule record is created). Defaults to false.

Automations: optional status automations for the new engagement — see
APIEngagementAutomationsModel. Setting Status to InProgress directly has the
same immediate effect as an Immediate InProgress trigger here — use Automations instead when
you want the transition to happen later (on a specific date) or want to schedule the Complete
transition, neither of which Status alone can do.

Request

Authorization

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Body Params

application/json

Required

Example

[
    {
        "companyID": 0,
        "officeID": 0,
        "divisionID": null,
        "title": "string",
        "code": "string",
        "type": "string",
        "period": "string",
        "year": null,
        "fieldworkStartDate": null,
        "fieldworkEndDate": null,
        "deliverableDueDate": null,
        "ownerID": null,
        "status": null,
        "addToSchedule": true,
        "professionalUsers": [
            {
                "userID": 0,
                "roleID": 0
            }
        ],
        "clientUsers": [
            {
                "userID": 0,
                "roleID": 0
            }
        ],
        "automations": {
            "inProgress": 0,
            "inProgressDate": null,
            "complete": 0,
            "completeDate": null
        }
    }
]

Responses

🟢201

application/json

Created: Engagements were successfully created.

Body

Example

[
    {
        "engagementID": 0,
        "importKey": "string",
        "divisionID": null,
        "companyID": 0,
        "title": "string",
        "code": "string",
        "type": "string",
        "period": "string",
        "year": null,
        "fieldworkStartDate": null,
        "fieldworkEndDate": null,
        "deliverableDueDate": null,
        "ownerID": null,
        "onSchedule": true,
        "globalModification": "2019-08-24T14:15:22.123Z",
        "status": {
            "value": 0,
            "name": "string"
        },
        "created": {
            "by": 0,
            "on": "2019-08-24T14:15:22.123Z"
        },
        "modified": {
            "by": 0,
            "on": "2019-08-24T14:15:22.123Z"
        },
        "professionalUsers": [
            {
                "userID": 0,
                "roleID": 0
            }
        ],
        "clientUsers": [
            {
                "userID": 0,
                "roleID": 0
            }
        ],
        "requests": [
            0
        ]
    }
]

🟠400

🟠403