Skip to main content
POST
/
v1
/
reminders
Create a reminder
curl --request POST \
  --url https://api.folk.app/v1/reminders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entity": {
    "id": "per_55175e81-9a52-4ac3-930e-82792c23499b"
  },
  "name": "Reminder on John Doe",
  "recurrenceRule": "DTSTART;TZID=Europe/Paris:20250717T090000\nRRULE:FREQ=WEEKLY;INTERVAL=1",
  "visibility": "public",
  "assignedUsers": [
    {
      "id": "usr_a45c30d8-19fc-4939-94c7-17dc5e46f476"
    },
    {
      "email": "[email protected]"
    }
  ]
}
'
{
  "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\nRRULE:FREQ=WEEKLY;INTERVAL=1",
    "visibility": "public",
    "assignedUsers": [
      {
        "id": "usr_a45c30d8-19fc-4939-94c7-17dc5e46f476",
        "fullName": "John Doe",
        "email": "[email protected]"
      }
    ],
    "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": "[email protected]"
    },
    "createdAt": "2021-01-01T00:00:00.000Z"
  }
}
Create a reminder linked to a person, company or deal.

​
Recurrence rule

The recurrence rules format is based on the iCalendar standard. 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.
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:
{
  "recurrenceRule": "DTSTART;TZID=Europe/Paris:20250717T090000\nRRULE:FREQ=WEEKLY;INTERVAL=1"
}
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.

Authorizations

​
Authorization
string
header
required

API key for authentication

Body

application/json
​
entity
object
required

The entity connected to the reminder. You can link people, companies and deals.

Example:
{
  "id": "per_55175e81-9a52-4ac3-930e-82792c23499b"
}
​
name
string
required

The name of the reminder.

Maximum string length: 255
Example:

"Reminder on John Doe"

​
recurrenceRule
string
required

The recurrence rule of the reminder. The recurrence rule is a string that follows the iCalendar format specified in RFC 5545. 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.

Maximum string length: 150
Example:

"DTSTART;TZID=Europe/Paris:20250717T090000\nRRULE:FREQ=WEEKLY;INTERVAL=1"

​
visibility
enum<string>
required

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.
Available options:
public,
private
​
assignedUsers
object[]

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.

Required array length: 1 - 50 elements
Example:
[
  {
    "id": "usr_a45c30d8-19fc-4939-94c7-17dc5e46f476"
  },
  { "email": "[email protected]" }
]

Response

The reminder created in the workspace.

​
data
object
required

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\nRRULE:FREQ=WEEKLY;INTERVAL=1",
  "visibility": "public",
  "assignedUsers": [
    {
      "id": "usr_a45c30d8-19fc-4939-94c7-17dc5e46f476",
      "fullName": "John Doe",
      "email": "[email protected]"
    }
  ],
  "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": "[email protected]"
  },
  "createdAt": "2021-01-01T00:00:00.000Z"
}
​
deprecations
string[]
Example:
["This field is deprecated"]