# Create a batch of engagements

**Create a batch of engagement letters asynchronously**
Submits a batch of engagement letter creation requests. The batch is processed
asynchronously — use the returned batch ID with the
`GET /api/v1/engagements/batch/{batchId}/status` endpoint to poll for completion
and retrieve the IDs of the created engagements.
**Batch-level options:**
- `name` — optional label for the batch
- `projectTemplateId` — apply a single project template to every engagement in the batch
- `includeAdditionalClients` — include additional clients when creating engagements
- `batchEngagements` — array of individual engagement records (required)

**Constraint:** You may provide either `projectTemplateId` (top-level) **or** `projectIds`
on individual engagements — not both.
**Real Example:**

```bash
curl --location 'https://{{host}}/api/v1/engagements/batch/create' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
  "name": "2024 Annual Batch",
  "batchEngagements": [
    {
      "clientId": 420,
      "fiscalYear": 2024,
      "partnerStaffId": 53,
      "managerStaffId": 15,
      "primaryContactId": 101
    },
    {
      "clientId": 421,
      "fiscalYear": 2024,
      "partnerStaffId": 53,
      "managerStaffId": 15,
      "primaryContactId": 201
    }
  ]
}'
```

Endpoint: POST /api/v1/engagements/batch/create
Version: 1.0.0
Security: BearerAuth

## Request fields (application/json):

  - `name` (string)
    Optional label for the batch
    Example: 2024 Annual Batch

  - `projectTemplateId` (integer)
    Project template ID to apply to every engagement in the batch. Cannot be combined with per-engagement `projectIds`.
    Example: 10

  - `includeAdditionalClients` (boolean)
    Whether to include additional clients when creating engagements
    Example: false

  - `batchEngagements` (array, required)
    List of engagement records to create

  - `batchEngagements.clientId` (integer, required)
    Unique identifier of the client
    Example: 420

  - `batchEngagements.fiscalYear` (integer, required)
    Fiscal year of the engagement
    Example: 2024

  - `batchEngagements.primaryContactId` (integer, required)
    Unique identifier of the primary client contact
    Example: 101

  - `batchEngagements.partnerStaffId` (integer)
    Unique identifier of the partner staff member
    Example: 53

  - `batchEngagements.managerStaffId` (integer)
    Unique identifier of the manager staff member
    Example: 15

  - `batchEngagements.secondaryContactId` (integer)
    Unique identifier of the secondary client contact
    Example: 102

  - `batchEngagements.billingContactId` (integer)
    Unique identifier of the billing contact
    Example: 103

  - `batchEngagements.engagementLetterTemplateId` (integer)
    Unique identifier of the engagement letter template to use
    Example: 5

  - `batchEngagements.documentTemplateId` (integer)
    Unique identifier of the document template to use
    Example: 7

  - `batchEngagements.engagementNameTemplate` (string)
    Template string used to generate the engagement name. Overrides the firm's default naming template.
    Example: {{fiscal_year.year}} {{letter_template.name}} {{client.number}}

  - `batchEngagements.startDate` (string)
    Engagement start date (YYYY-MM-DD)
    Example: 2024-01-01

  - `batchEngagements.endDate` (string)
    Engagement end date (YYYY-MM-DD)
    Example: 2024-12-31

  - `batchEngagements.ccStaffIds` (array)
    List of staff member IDs to CC on the engagement
    Example: [20,21]

  - `batchEngagements.projectIds` (array)
    List of project IDs to associate with this engagement. Cannot be used when a top-level `projectTemplateId` is provided.
    Example: [301,302]

## Response 200 fields (application/json):

  - `id` (integer)
    Unique identifier of the created engagement batch
    Example: 9001