> For the complete documentation index, see [llms.txt](https://api-docs.conversion.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.conversion.ai/engagements.md).

# Engagements

## Concepts

**Engagements** in Conversion are events that happen for a contact. These can include website page visits, form submissions, actions in the product, or even sales meetings.

**Custom engagements** are a subset of engagements, representing engagements that aren't natively tracked in Conversion and synced in from external sources. Examples include:

* Meetings
* Calls
* Product usage

## Batch Track Custom engagements

Record custom engagements for contacts.

**Rate limits:** 10 / second, 200 custom engagements per batch

**Method:** `POST` 

**Route:** `/v1/activities/batch`

**Request Body:**

```json
{
  "batch": [
    {
      "id": "your_custom_engagement_id_123",
      "contactEmail": "john@example.com",
      "type": "PRODUCT_ACTIVITY",
      "name": "Product Demo Completed",
      "description": "Customer completed full product demonstration session",
      "data": { // Include any relevant engagement metadata
        "duration_minutes": 45,
        "demo_type": "interactive",
        "interest_level": "high",
        ...
      }
    },
    ...
  ]
}
```

**Field Descriptions:**

* `batch` (required): List of contacts to create/update
  * `id` (optional): Your system's custom engagement id
  * `contactEmail` (required): The contact's email address to track the custom engagement for
  * `type` (required): The type of this custom engagement
  * `name` (optional): The name of this custom engagement
  * `description` (optional): The description of this custom engagement
  * `createdAt` (optional): Defaults to now. When the custom engagement was created in your system.
  * `data` (optional): Key-value pairs for the custom engagement's data fields

**Response:**

Empty object response.