***

title: Filter engagements by CRM object IDs
subtitle: 'Use CRM company, contact, and deal IDs with GET /v2/engagements'
slug: filtering-engagements-by-crm-object-ids
---------------------------------------------

Use `GET /v2/engagements` with `filter[crm_associations][eq]` when your app already has IDs from HubSpot, Salesforce, or another connected CRM and you want the related AskElephant engagements.

## Request shape

For readability, the examples below use indexed bracket syntax:

```text
filter[crm_associations][eq][0][id]=12345
filter[crm_associations][eq][0][object_type]=company
```

Those query params represent one CRM association object with this shape:

```json
[
  {
    "id": "123",
    "object_type": "company"
  }
]
```

The API also accepts the same value as a JSON-encoded array string in `filter[crm_associations][eq]`, but the bracket form is usually easier to read in docs and examples.

When using these raw bracket query params with `curl`, add `--globoff` so `curl` does not treat `[]` as URL globbing syntax.

Each object includes:

* `id`: the CRM record ID from your connected CRM
* `object_type`: the CRM object type to match

For engagements, the common `object_type` values are:

* `company`
* `contact`
* `deal`

The CRM source is inferred from the workspace's connected CRM. You do not pass a separate CRM provider field.

## Filter by CRM company ID

```bash
curl --request GET \
  --globoff \
  --url 'https://app.askelephant.ai/api/v2/engagements?filter[crm_associations][eq][0][id]=12345&filter[crm_associations][eq][0][object_type]=company&order_by=updated_at:desc&limit=25' \
  --header 'Authorization: sk-apik_<id>.<secret>' \
  --header 'Accept: application/json'
```

Decoded filter value:

```json
[
  {
    "id": "12345",
    "object_type": "company"
  }
]
```

## Filter by CRM contact ID

```bash
curl --request GET \
  --globoff \
  --url 'https://app.askelephant.ai/api/v2/engagements?filter[crm_associations][eq][0][id]=67890&filter[crm_associations][eq][0][object_type]=contact&order_by=updated_at:desc&limit=25' \
  --header 'Authorization: sk-apik_<id>.<secret>' \
  --header 'Accept: application/json'
```

Decoded filter value:

```json
[
  {
    "id": "67890",
    "object_type": "contact"
  }
]
```

## Filter by CRM deal ID

```bash
curl --request GET \
  --globoff \
  --url 'https://app.askelephant.ai/api/v2/engagements?filter[crm_associations][eq][0][id]=deal_abc123&filter[crm_associations][eq][0][object_type]=deal&order_by=updated_at:desc&limit=25' \
  --header 'Authorization: sk-apik_<id>.<secret>' \
  --header 'Accept: application/json'
```

Decoded filter value:

```json
[
  {
    "id": "deal_abc123",
    "object_type": "deal"
  }
]
```

## Filter by multiple CRM objects

You can pass more than one CRM object in the same request.

```bash
curl --request GET \
  --globoff \
  --url 'https://app.askelephant.ai/api/v2/engagements?filter[crm_associations][eq][0][id]=12345&filter[crm_associations][eq][0][object_type]=company&filter[crm_associations][eq][1][id]=67890&filter[crm_associations][eq][1][object_type]=contact&filter[crm_associations][eq][2][id]=deal_abc123&filter[crm_associations][eq][2][object_type]=deal&order_by=updated_at:desc&limit=25' \
  --header 'Authorization: sk-apik_<id>.<secret>' \
  --header 'Accept: application/json'
```

Decoded filter value:

```json
[
  {
    "id": "12345",
    "object_type": "company"
  },
  {
    "id": "67890",
    "object_type": "contact"
  },
  {
    "id": "deal_abc123",
    "object_type": "deal"
  }
]
```

## How engagement filtering combines

Engagement filtering uses bucket semantics:

* AskElephant `company_ids` and CRM `company` associations share the company bucket
* AskElephant `contact_ids` and CRM `contact` associations share the participant bucket
* CRM `deal` associations populate a deal bucket

Values in the same bucket use OR semantics. Populated buckets combine with AND semantics.

Example: require a CRM company match and a CRM deal match in the same request:

```bash
curl --request GET \
  --globoff \
  --url 'https://app.askelephant.ai/api/v2/engagements?filter[crm_associations][eq][0][id]=12345&filter[crm_associations][eq][0][object_type]=company&filter[crm_associations][eq][1][id]=deal_abc123&filter[crm_associations][eq][1][object_type]=deal&filter[start_at][gte]=2026-03-01T00:00:00.000Z&order_by=updated_at:desc&limit=25' \
  --header 'Authorization: sk-apik_<id>.<secret>' \
  --header 'Accept: application/json'
```

## Limits and tips

* `filter[crm_associations][eq]` supports up to 20 CRM association objects.
* Use CRM record IDs here, not AskElephant `cmp_...` or `cnt_...` IDs.
* Add `expand=companies,contacts,owner` if you want richer context in the response.

See also: [Searching engagements](/searching-engagements) and [Pagination and filtering](/pagination)