---
title: "Add a reminder to many contacts (v2)"
method: POST
path: "/v2/reminders/batch-create"
tags: ["reminders"]
---

# Add a reminder to many contacts (v2)

`POST /v2/reminders/batch-create`

## Request

- Base URL: `https://api.prod.getdex.com`
- URL: `https://api.prod.getdex.com/v2/reminders/batch-create`
- Auth: HTTP bearer

Create one reminder per contact for up to 500 contacts (`contact_ids`; duplicates are dropped), each linked to its one contact and sharing `reminder`'s `text`, `due_at_date`, `due_at_time` and `assignee_id` (omitted = the caller, `null` = unassigned, otherwise an active workspace member), so completing one leaves the others open. All or nothing: a contact outside the workspace or an invalid assignee is a 400 `invalid_reference` and creates no reminder. The assignee is notified once for the whole batch. Viewers are refused. Workspace-only: send the `X-Dex-Workspace` header (400 `workspace_context_required` without it). **Requires an `Idempotency-Key` header**. Returns `{ data: { reminders: [...] } }` in `contact_ids` order with status 201.

## Request body

- object
  - `reminder` object, required
    - `text` string
    - `due_at_date` unknown, required
    - `due_at_time` unknown
    - `assignee_id` union
      - unknown
      - string
  - `contact_ids` string[], required

## Response `201`

Created

- object
  - `data` object, required
    - `reminders` object[], required
      - `id` string, uuid, required
      - `user_id` string
      - `workspace_id` string, uuid, nullable
      - `assignee_id` string, nullable
      - `text` string, nullable
      - `due_at_date` union
        - string, date-time
        - unknown
      - `due_at_time` union
        - string, date-time
        - unknown
        - string
      - `is_complete` boolean
      - `email_sent` boolean
      - `push_notification_sent` boolean
      - `recurrence` string, nullable
      - `last_completed_at` union
        - string, date-time
        - unknown
      - `next_occurrence_at` union
        - string, date-time
        - unknown
      - `created_at` union
        - string, date-time
        - unknown
      - `is_overdue` boolean
      - `next_cursor` string
      - `reminders_contacts` object[]
      - `reminders_tags` object[]
      - `users` object, nullable

## Other responses

- `400`: Request body failed validation.
- `401`: Missing or invalid API key.
- `403`: Valid key, insufficient permission.
- `404`: Resource does not exist.
- `409`: Request conflicts with the current state of the resource.
- `429`: Rate limit exceeded.
- `500`: Unexpected server error.

## Changes

- **2026-10-19** `0d35f04ff3ed`: 1 info
  - added the optional property `data/reminders/items/reminders_tags` to the response with the `201` status
- **2026-10-16** `a4a42e45e725`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/getdex/apis/dex-public-api/changes/v2/reminders/batch-create/post.md)

---

[API](https://skmtc.dev/getdex/apis/dex-public-api.md) · [All operations](https://skmtc.dev/getdex/apis/dex-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/getdex/apis/dex-public-api/revisions/657247ddcf7c?raw)