---
title: "Get or create the inbound call's engagement at the start of the IVR"
method: POST
path: "/api/v1/ivr/engagement"
tags: ["IVR"]
---

# Get or create the inbound call's engagement at the start of the IVR

`POST /api/v1/ivr/engagement`

## Request

- Base URL: `https://api.cloverhealth.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.cloverhealth.com/api/v1/ivr/engagement`
- Auth: API key in header `X-MC2-Signature`

GE-3578. Called by the `engagement-init` Twilio Function before `ani-lookup`.

Twilio's `studio.started` event is what normally creates the inbound engagement, and
it can reach MC2 well after the IVR has already asked for the engagement id. This
creates the row first, with the same defaults, so the late event finds it. Idempotent:
a repeat for the same `callSid` returns the same engagement with `created: false`.

## Request body

- IVREngagementInitRequest: Posted by the `engagement-init` Twilio Function at the start of an inbound call (GE-3578). `callSid` must be a voice CallSid: a messaging SID here would mint a phantom CALL engagement, the same hazard `studio.started` guards against with its `CA` prefix check. `ani` is optional because a Genesys-transferred call can reach the flow without a caller number, and refusing the request would leave that call with no engagement id. `dnis` is the number the caller dialed, which `voice.initiated` also records; it is optional for the same reason.
  - `callSid` string, required
  - `ani` string, nullable
  - `dnis` string, nullable

## Response `200`

OK

- IVREngagementInitResponse
  - `engagementId` string, required
  - `created` boolean, required

## Changes

- **2026-10-27** `3981d9e53794`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/cloverhealth/apis/clover-api/changes/api/v1/ivr/engagement/post.md)

---

[API](https://skmtc.dev/cloverhealth/apis/clover-api.md) - [All operations](https://skmtc.dev/cloverhealth/apis/clover-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cloverhealth/apis/clover-api/revisions/824d541751f2?raw)