---
title: "Create a Reminder"
method: POST
path: "/v2/reminders"
tags: ["Reminders"]
---

# Create a Reminder

`POST /v2/reminders`

Creates a new Reminder. Exactly one of `company`, `person`, or `opportunity` must be provided.

The `creator` of the new reminder is the user associated with the API key.

## Request body

- union — Request body for creating a reminder. Discriminated by `type` — see `reminders.OneTimeReminderToBeCreated` and `reminders.RecurringReminderToBeCreated`. Exactly one of `company`, `person`, or `opportunity` must be provided.
  - RemindersOneTimeReminderToBeCreated — Shared fields common to both `reminders.OneTimeReminderToBeCreated` and `reminders.RecurringReminderToBeCreated`. Not used directly — callers send one of the concrete variants discriminated by `type` on `ReminderToBeCreated`.
    - `owner` PersonReference, required
      - `id` integer, required — The persons's unique identifier
    - `content` string, nullable — Free-form text attached to the reminder.
    - `entity` union, required — The entity the reminder is attached to. Exactly one of `company`, `person`, or `opportunity` can be tagged on a reminder — the variant is selected by the `type` discriminator.
      - RemindersTaggedCompany — Reference to a Company tagged on a reminder being created.
        - `type` 'company', required — Discriminator. Always `company` for this variant.
        - `id` integer, required — The company's unique identifier.
      - RemindersTaggedPerson — Reference to a Person tagged on a reminder being created. Must reference an external person or collaborator.
        - `type` 'person', required — Discriminator. Always `person` for this variant.
        - `id` integer, required — The person's unique identifier.
      - RemindersTaggedOpportunity — Reference to an Opportunity tagged on a reminder being created.
        - `type` 'opportunity', required — Discriminator. Always `opportunity` for this variant.
        - `id` integer, required — The opportunity's unique identifier.
  - RemindersRecurringReminderToBeCreated — Shared fields common to both `reminders.OneTimeReminderToBeCreated` and `reminders.RecurringReminderToBeCreated`. Not used directly — callers send one of the concrete variants discriminated by `type` on `ReminderToBeCreated`.
    - `owner` PersonReference, required
      - `id` integer, required — The persons's unique identifier
    - `content` string, nullable — Free-form text attached to the reminder.
    - `entity` union, required — The entity the reminder is attached to. Exactly one of `company`, `person`, or `opportunity` can be tagged on a reminder — the variant is selected by the `type` discriminator.
      - RemindersTaggedCompany — Reference to a Company tagged on a reminder being created.
        - `type` 'company', required — Discriminator. Always `company` for this variant.
        - `id` integer, required — The company's unique identifier.
      - RemindersTaggedPerson — Reference to a Person tagged on a reminder being created. Must reference an external person or collaborator.
        - `type` 'person', required — Discriminator. Always `person` for this variant.
        - `id` integer, required — The person's unique identifier.
      - RemindersTaggedOpportunity — Reference to an Opportunity tagged on a reminder being created.
        - `type` 'opportunity', required — Discriminator. Always `opportunity` for this variant.
        - `id` integer, required — The opportunity's unique identifier.

## Response `201`

Created

- union — A reminder to follow up with a person, company, or opportunity. Discriminated by `type` — `one-time` reminders fire once on `dueDate`, and `recurring` reminders reset on a cadence.
  - RemindersOneTimeReminder — Shared fields common to both `OneTimeReminder` and `RecurringReminder`. Not used directly — callers receive one of the concrete variants discriminated by `type` on `Reminder`.
    - `id` integer, required — The reminder's unique identifier
    - `content` string, nullable, required — Free-form text attached to the reminder.
    - `dueDate` string, date-time, required — When the reminder is next due.
    - `creator` PersonReference, required
      - `id` integer, required — The persons's unique identifier
    - `owner` PersonReference, required
      - `id` integer, required — The persons's unique identifier
    - `completer` PersonReference, required
      - `id` integer, required — The persons's unique identifier
    - `company` CompanyReference, required
      - `id` integer, required — The company's unique identifier
    - `person` PersonReference, required
      - `id` integer, required — The persons's unique identifier
    - `opportunity` OpportunityReference, required
      - `id` integer, required — The opportunity's unique identifier
    - `createdAt` string, date-time, required — When the reminder was created.
    - `updatedAt` string, date-time, nullable, required — When the reminder was last updated. `null` if the reminder has never been updated.
  - RemindersRecurringReminder — Shared fields common to both `OneTimeReminder` and `RecurringReminder`. Not used directly — callers receive one of the concrete variants discriminated by `type` on `Reminder`.
    - `id` integer, required — The reminder's unique identifier
    - `content` string, nullable, required — Free-form text attached to the reminder.
    - `dueDate` string, date-time, required — When the reminder is next due.
    - `creator` PersonReference, required
      - `id` integer, required — The persons's unique identifier
    - `owner` PersonReference, required
      - `id` integer, required — The persons's unique identifier
    - `completer` PersonReference, required
      - `id` integer, required — The persons's unique identifier
    - `company` CompanyReference, required
      - `id` integer, required — The company's unique identifier
    - `person` PersonReference, required
      - `id` integer, required — The persons's unique identifier
    - `opportunity` OpportunityReference, required
      - `id` integer, required — The opportunity's unique identifier
    - `createdAt` string, date-time, required — When the reminder was created.
    - `updatedAt` string, date-time, nullable, required — When the reminder was last updated. `null` if the reminder has never been updated.

## Other responses

- `400` — Bad Request
- `403` — Forbidden
- `404` — Not Found
- `default` — Errors

---

[API](https://skmtc.net/affinity/apis/affinity-api-v2.md) · [All operations](https://skmtc.net/affinity/apis/affinity-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/affinity/affinity-api-v2/revisions/4c2891c31b7f/schema)