> ## Documentation Index
> Fetch the complete documentation index at: https://developer.folk.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a reminder

> Create a new reminder in the workspace.

Create a reminder linked to a person, company or deal.

### Recurrence rule

The recurrence rules format is based on the [iCalendar standard](https://icalendar.org/iCalendar-RFC-5545/3-8-5-3-recurrence-rule.html).

However, we don't support the full spec, but only a subset of the features.
The format of the recurrence must be the following:

```
DTSTART;TZID=<timezone>:<date>T<time>
RRULE:<recurrence parameters>
```

For example, a reminder that should be triggered every week at 9:00 AM Paris time, starting on July 17th 2025 would be:

```
DTSTART;TZID=Europe/Paris:20250717T090000
RRULE:FREQ=WEEKLY;INTERVAL=1
```

You can find a list of timezone identifiers [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).

<Note>
  There must always be a newline between the `DTSTART` and `RRULE` lines.

  In JSON encoding, the newline is represented as `\n`. The previous example would be encoded as:

  ```json theme={null}
  {
    "recurrenceRule": "DTSTART;TZID=Europe/Paris:20250717T090000\nRRULE:FREQ=WEEKLY;INTERVAL=1"
  }
  ```
</Note>

Only the following recurrence parameters are supported:

* No repeat: `RRULE:COUNT=1`
* Every weekday: `RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;INTERVAL=1`
* Every week: `RRULE:FREQ=WEEKLY;INTERVAL=1`
* Every 2 weeks: `RRULE:FREQ=WEEKLY;INTERVAL=2`
* Every month: `RRULE:FREQ=MONTHLY;INTERVAL=1`
* Every quarter: `RRULE:FREQ=MONTHLY;INTERVAL=3`
* Every year: `RRULE:FREQ=YEARLY;INTERVAL=1`

Supplying any other type of recurrence will result in a validation error.

### Visibility

The visibility of the reminder can be set to `public` or `private`.

* `public`: The reminder is visible to all users in the workspace.
* `private`: The reminder is visible only to the current user.

If the visibility is set to `public`, you must provide a list of users to be notified when the reminder is triggered.

If the visibility is set to `private`, the current user is automatically notified.


## OpenAPI

````yaml post /v1/reminders
openapi: 3.1.0
info:
  title: Folk External API
  description: >-
    Folk's public REST API lets you manage workspaces, groups, contacts, and
    real-time triggers.
  version: '2025-06-09'
  contact:
    name: folk
    email: tech@folk.app
    url: https://folk.app
servers:
  - url: https://api.folk.app
    description: Folk's public API production base URL.
    x-internal: false
security: []
tags:
  - name: Companies
    description: Operations related to companies.
  - name: Deals
    description: Operations related to deals.
  - name: Groups
    description: Operations related to groups.
  - name: Interactions
    description: Operations related to interactions.
  - name: Notes
    description: Operations related to notes.
  - name: People
    description: Operations related to people.
  - name: Reminders
    description: Operations related to reminders.
  - name: Tasks
    description: Operations related to tasks.
  - name: Users
    description: Operations related to users.
  - name: Webhooks
    description: Operations related to webhooks.
paths:
  /v1/reminders:
    post:
      tags:
        - Reminders
      summary: Create a reminder
      description: Create a new reminder in the workspace.
      operationId: createReminder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                entity:
                  type: object
                  properties:
                    id:
                      type: string
                      minLength: 40
                      maxLength: 40
                  required:
                    - id
                  additionalProperties: false
                  description: >-
                    The entity connected to the reminder. You can link people,
                    companies and deals.
                  example:
                    id: per_55175e81-9a52-4ac3-930e-82792c23499b
                name:
                  type: string
                  maxLength: 255
                  description: The name of the reminder.
                  example: Reminder on John Doe
                recurrenceRule:
                  type: string
                  maxLength: 150
                  description: >-
                    The recurrence rule of the reminder. The recurrence rule is
                    a string that follows the iCalendar format specified in [RFC
                    5545](https://icalendar.org/iCalendar-RFC-5545/3-8-5-3-recurrence-rule.html).

                    We support only a subset of the iCalendar format:


                    ```

                    DTSTART;TZID=<timezone>:<date>T<time>

                    RRULE:<recurrence parameters>

                    ```


                    Only the following recurrence parameters are supported:


                    - No repeat: `RRULE:COUNT=1`

                    - Every weekday:
                    `RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;INTERVAL=1`

                    - Every week: `RRULE:FREQ=WEEKLY;INTERVAL=1`

                    - Every 2 weeks: `RRULE:FREQ=WEEKLY;INTERVAL=2`

                    - Every month: `RRULE:FREQ=MONTHLY;INTERVAL=1`

                    - Every quarter: `RRULE:FREQ=MONTHLY;INTERVAL=3`

                    - Every year: `RRULE:FREQ=YEARLY;INTERVAL=1`


                    Supplying any other type of recurrence will result in a
                    validation error.
                          
                  example: |-
                    DTSTART;TZID=Europe/Paris:20250717T090000
                    RRULE:FREQ=WEEKLY;INTERVAL=1
                visibility:
                  type: string
                  enum:
                    - public
                    - private
                  description: >-
                    The visibility of the reminder.


                    - `public`: The reminder is visible to all users in the
                    workspace.

                    - `private`: The reminder is visible only to the current
                    user.
                        
                assignedUsers:
                  type: array
                  items:
                    anyOf:
                      - type: object
                        properties:
                          id:
                            type: string
                            minLength: 40
                            maxLength: 40
                        required:
                          - id
                        additionalProperties: false
                      - type: object
                        properties:
                          email:
                            type: string
                            maxLength: 254
                        required:
                          - email
                        additionalProperties: false
                  minItems: 1
                  maxItems: 50
                  description: >-
                    A list of workspace users to be notified when the reminder
                    is triggered. Only required for public reminders. For
                    private reminders, this field must be omitted and the
                    current user is automatically notified.
                  example:
                    - id: usr_a45c30d8-19fc-4939-94c7-17dc5e46f476
                    - email: john.doe@example.com
              required:
                - entity
                - name
                - recurrenceRule
                - visibility
              additionalProperties: false
      responses:
        '200':
          description: The reminder created in the workspace.
          links:
            updateReminder:
              operationId: updateReminder
              parameters:
                reminderId: $response.body#/data/id
              description: >-
                The id returned by the `POST /v1/reminders` operation can be
                used as an input to the `PATCH /v1/reminders/:reminderId`
                operation to update the reminder.
            getReminder:
              operationId: getReminder
              parameters:
                companyId: $response.body#/data/id
              description: >-
                The id returned by the `POST /v1/reminders` operation can be
                used as an input to the `GET /v1/reminders/:reminderId`
                operation to retrieve the reminder.
            deleteReminder:
              operationId: deleteReminder
              parameters:
                reminderId: $response.body#/data/id
              description: >-
                The id returned by the `POST /v1/reminders` operation can be
                used as an input to the `DELETE /v1/reminders/:reminderId`
                operation to delete the reminder.
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Reminder'
                  deprecations:
                    type: array
                    items:
                      type: string
                    example:
                      - This field is deprecated
                required:
                  - data
              example:
                data:
                  id: rmd_91118b73-5a75-480b-b8e3-a33671c35cdc
                  name: Reminder on John Doe
                  entity:
                    id: per_55175e81-9a52-4ac3-930e-82792c23499b
                    entityType: person
                    fullName: John Doe
                  recurrenceRule: |-
                    DTSTART;TZID=Europe/Paris:20250717T090000
                    RRULE:FREQ=WEEKLY;INTERVAL=1
                  visibility: public
                  assignedUsers:
                    - id: usr_a45c30d8-19fc-4939-94c7-17dc5e46f476
                      fullName: John Doe
                      email: john.doe@example.com
                  nextTriggerTime: '2025-07-17T09:00:00.000Z'
                  lastTriggerTime: '2025-05-17T09:00:00.000Z'
                  createdBy:
                    id: usr_bc984b3f-0386-434d-82d7-a91eb6badd71
                    fullName: John Doe
                    email: john.doe@example.com
                  createdAt: '2021-01-01T00:00:00.000Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      security:
        - bearerApiKeyAuth: []
components:
  headers:
    X-RateLimit-Limit:
      schema:
        type: integer
        example: 1000
      description: >-
        The maximum number of requests that you can make in the current rate
        limit window.
    X-RateLimit-Remaining:
      schema:
        type: integer
        example: 998
      description: The number of requests remaining in the current rate limit window.
    X-RateLimit-Reset:
      schema:
        type: integer
        example: 1747322958
      description: >-
        The time at which the current rate limit window resets, in UTC epoch
        seconds.
    Retry-After:
      schema:
        type: integer
        example: 60
      description: >-
        The number of seconds to wait before making a new request after hitting
        the rate limit.
  schemas:
    Reminder:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
          maxLength: 255
        entity:
          type: object
          properties:
            id:
              type: string
              minLength: 40
              maxLength: 40
              description: The ID of the entity connected to the reminder.
              example: per_55175e81-9a52-4ac3-930e-82792c23499b
            entityType:
              type: string
              enum:
                - person
                - company
                - object
              description: >-
                The type of the entity connected to the reminder. Can be
                `person`, `company` or `object`.
              example: person
            fullName:
              type: string
              maxLength: 1000
              description: The full name of the entity connected to the reminder.
              example: John Doe
          required:
            - id
            - entityType
            - fullName
        recurrenceRule:
          type: string
          description: >-
            The recurrence rule of the reminder. The recurrence rule is a string
            that follows the iCalendar format specified in [RFC
            5545](https://icalendar.org/iCalendar-RFC-5545/3-8-5-3-recurrence-rule.html).
          example: |-
            DTSTART;TZID=Europe/Paris:20250717T090000
            RRULE:FREQ=WEEKLY;INTERVAL=1
        visibility:
          type: string
          enum:
            - public
            - private
          description: |-
            The visibility of the reminder.

            - `public`: The reminder is visible to all users in the workspace.
            - `private`: The reminder is visible only to the current user.
                
        assignedUsers:
          type: array
          items:
            $ref: '#/components/schemas/User'
          description: >-
            A list of workspace users to be notified when the reminder is
            triggered. For private reminders, only the current user is notified.
          example:
            - id: usr_a45c30d8-19fc-4939-94c7-17dc5e46f476
              fullName: John Doe
              email: john.doe@example.com
        nextTriggerTime:
          type:
            - string
            - 'null'
          format: date-time
          description: The next trigger time of the reminder.
          example: '2025-07-17T09:00:00.000Z'
        lastTriggerTime:
          type:
            - string
            - 'null'
          format: date-time
          description: The last trigger time of the reminder.
          example: '2025-05-17T09:00:00.000Z'
        createdBy:
          allOf:
            - $ref: '#/components/schemas/User'
            - description: The user who created the reminder.
        createdAt:
          type:
            - string
            - 'null'
          minLength: 20
          maxLength: 40
          description: The date and time the reminder was created, in ISO format.
          example: '2021-01-01T00:00:00.000Z'
      required:
        - id
        - name
        - entity
        - recurrenceRule
        - visibility
        - assignedUsers
        - nextTriggerTime
        - lastTriggerTime
        - createdBy
        - createdAt
      description: A reminder linked to an entity.
      example:
        id: rmd_91118b73-5a75-480b-b8e3-a33671c35cdc
        name: Reminder on John Doe
        entity:
          id: per_55175e81-9a52-4ac3-930e-82792c23499b
          entityType: person
          fullName: John Doe
        recurrenceRule: |-
          DTSTART;TZID=Europe/Paris:20250717T090000
          RRULE:FREQ=WEEKLY;INTERVAL=1
        visibility: public
        assignedUsers:
          - id: usr_a45c30d8-19fc-4939-94c7-17dc5e46f476
            fullName: John Doe
            email: john.doe@example.com
        nextTriggerTime: '2025-07-17T09:00:00.000Z'
        lastTriggerTime: '2025-05-17T09:00:00.000Z'
        createdBy:
          id: usr_bc984b3f-0386-434d-82d7-a91eb6badd71
          fullName: John Doe
          email: john.doe@example.com
        createdAt: '2021-01-01T00:00:00.000Z'
    User:
      type: object
      properties:
        id:
          type: string
        fullName:
          type: string
        email:
          type: string
      required:
        - id
        - fullName
        - email
      description: A user in the workspace.
      example:
        id: usr_bc984b3f-0386-434d-82d7-a91eb6badd71
        fullName: John Doe
        email: john.doe@example.com
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: RATE_LIMIT_EXCEEDED
            message:
              type: string
              example: You have exceeded your rate limit.
            documentationUrl:
              type: string
              format: uri
              example: https://developer.folk.app/api-reference/errors#rate-limiting
            requestId:
              type: string
              format: uuid
              example: 123e4567-e89b-12d3-a456-426614174000
            timestamp:
              type: string
              format: date-time
              example: '2025-10-01T12:00:00Z'
            details:
              type: object
              additionalProperties: true
              example:
                limit: 1000
                remaining: 0
                retryAfter: '2025-10-01T12:00:00Z'
          required:
            - code
            - message
            - documentationUrl
            - requestId
            - timestamp
      required:
        - error
      description: Error response containing error details.
  responses:
    BadRequest:
      description: The request was unacceptable, often due to missing an invalid parameter.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INVALID_REQUEST
              message: The request was invalid.
              documentationUrl: https://developer.folk.app/api-reference/errors#bad-request
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    Unauthorized:
      description: No valid API key provided.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNAUTHORIZED
              message: No valid API key provided.
              documentationUrl: https://developer.folk.app/api-reference/errors#unauthorized
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    Forbidden:
      description: The API key doesn’t have permissions to perform the request.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: FORBIDDEN
              message: The API key doesn’t have permissions to perform the request.
              documentationUrl: https://developer.folk.app/api-reference/errors#forbidden
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    NotFound:
      description: The requested resource doesn’t exist.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: RESOURCE_NOT_FOUND
              message: The requested resource was not found.
              documentationUrl: https://developer.folk.app/api-reference/errors#not-found
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    UnprocessableEntity:
      description: >-
        The request was unacceptable, often due to missing or invalid
        parameters.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNPROCESSABLE_ENTITY
              message: Invalid query parameters
              documentationUrl: >-
                https://developer.folk.app/api-reference/errors#unprocessable-entity
              details:
                issues:
                  - code: too_small
                    minimum: 1
                    type: number
                    inclusive: true
                    exact: false
                    message: Number must be greater than or equal to 1
                    path:
                      - limit
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    TooManyRequests:
      description: >-
        Too many requests hit the API too quickly. We recommend an exponential
        backoff of your requests.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: RATE_LIMIT_EXCEEDED
              message: The rate limit has been exceeded.
              documentationUrl: https://developer.folk.app/api-reference/errors#rate-limiting
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
              details:
                limit: 1000
                remaining: 0
                retryAfter: '2025-10-01T12:00:00Z'
    InternalServerError:
      description: Something went wrong on our end.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INTERNAL_SERVER_ERROR
              message: An internal server error occurred.
              documentationUrl: >-
                https://developer.folk.app/api-reference/errors#internal-server-error
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    ServiceUnavailable:
      description: The server is overloaded or down for maintenance.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: SERVICE_UNAVAILABLE
              message: The service is currently unavailable.
              documentationUrl: >-
                https://developer.folk.app/api-reference/errors#service-unavailable
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
  securitySchemes:
    bearerApiKeyAuth:
      type: http
      scheme: bearer
      description: API key for authentication

````