Interaction API is currently in private beta. If interested, reach out to folks@folk.app.

Overview

API documentation preview for Interactions endpoints.

Base URL: https://api.folk.app

Authentication: Bearer API key in the Authorization header.

Authorization: Bearer <your-api-key>

Interactions represent touchpoints with people, companies, or objects in your workspace. There are two categories:

Logged interactions (interactionType: logged) — manually logged by users (calls, meetings, coffee, etc.). Writable via the API.
Imported interactions (interactionType: email, calendar, whatsapp) — synced from connected sources. Read-only via the API.

List endpoints return preview content only (subject + snippet for email/calendar, title + content for logged). Full email/calendar body is only returned by Get an interaction.

Endpoints

Method	Path	Summary
`POST`	`/v1/interactions`	Create an interaction
`GET`	`/v1/interactions/past`	List past interactions
`GET`	`/v1/interactions/upcoming`	List upcoming interactions
`GET`	`/v1/interactions/{interactionId}`	Get an interaction
`PATCH`	`/v1/interactions/{interactionId}`	Update an interaction
`DELETE`	`/v1/interactions/{interactionId}`	Delete an interaction

Create an interaction

POST /v1/interactions

Creates a new interaction with a person or a company.

Only logged interactions can be created. Imported interactions (email, calendar, WhatsApp) sync automatically from connected sources.

Request body

Field	Type	Required	Description
`entity.id`	string (40 chars)	Yes	The person (`per_…`) or company (`com_…`) connected to the interaction.
`dateTime`	string (ISO 8601)	Yes	The date and time of the interaction.
`title`	string (max 255)	Yes	The title of the interaction.
`content`	string (max 100,000)	Yes	The multi-line content of the interaction.
`activityType`	string	No	The logged activity type. Can be a predefined activity, a messaging app, or an emoji. See Activity types below.
`type`	string	No	Deprecated. Use `activityType` instead.

Example request

{   "entity": {     "id": "per_55175e81-9a52-4ac3-930e-82792c23499b"   },   "dateTime": "2025-07-17T09:00:00.000Z",   "title": "Coffee with John Doe",   "content": "Had a coffee with John Doe\nDiscussed the new project.",   "activityType": "coffee" }

Response `200`

Returns the created LoggedInteraction.

{   "data": {     "id": "lit_b049db09-c03d-4f32-96d6-d314760add5d",     "interactionType": "logged",     "from": {       "type": "user",       "value": "usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c",       "name": "John Doe"     },     "to": {       "type": "person",       "value": "per_55175e81-9a52-4ac3-930e-82792c23499b",       "name": "John Doe"     },     "entity": {       "id": "per_55175e81-9a52-4ac3-930e-82792c23499b",       "entityType": "person",       "fullName": "John Doe"     },     "dateTime": "2025-07-17T09:00:00.000Z",     "title": "Coffee with John Doe",     "content": "Had a coffee with John Doe\nDiscussed the new project.",     "privacyLevel": "sharedFull",     "type": "coffee",     "activityType": "coffee"   } }

Errors

400 Bad Request · 401 Unauthorized · 403 Forbidden · 404 Not Found · 422 Unprocessable Entity · 429 Too Many Requests · 500 Internal Server Error · 503 Service Unavailable

List past interactions

GET /v1/interactions/past

Retrieves paginated past interactions linked to a person, company, or object.

Query parameters

Parameter	Required	Description
`entity.id`	Yes	The person, company, or object linked to interactions.
`cursor`	No	Cursor for pagination. Omit on the first call; use `pagination.nextLink` from a previous response for subsequent pages.

Example request

GET <https://api.folk.app/v1/interactions/past?entity.id=per_55175e81-9a52-4ac3-930e-82792c23499b>

Response `200`

Returns a paginated list of Interaction objects (logged, email, calendar, or WhatsApp).

{   "data": {     "items": [       {         "id": "lit_b049db09-c03d-4f32-96d6-d314760add5d",         "interactionType": "logged",         "from": { "type": "user", "value": "usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c", "name": "John Doe" },         "to": { "type": "person", "value": "per_55175e81-9a52-4ac3-930e-82792c23499b", "name": "John Doe" },         "entity": { "id": "per_55175e81-9a52-4ac3-930e-82792c23499b", "entityType": "person", "fullName": "John Doe" },         "dateTime": "2025-07-17T09:00:00.000Z",         "privacyLevel": "sharedFull",         "title": "Coffee with John Doe",         "content": "Had a coffee with John Doe\nDiscussed the new project.",         "type": "coffee",         "activityType": "coffee"       }     ],     "pagination": {       "nextLink": "<https://api.folk.app/v1/interactions/past?entity.id=per_55175e81-9a52-4ac3-930e-82792c23499b&cursor=eyJmb28iOiJiYXIifQ%3D%3D>"     }   } }

Errors

400 · 401 · 403 · 404 · 422 · 429 · 500 · 503

List upcoming interactions

GET /v1/interactions/upcoming

Retrieves paginated upcoming interactions linked to a person, company, or object.

Query parameters

Parameter	Required	Description
`entity.id`	Yes	The person, company, or object linked to interactions.
`cursor`	No	Cursor for pagination. Omit on the first call; use `pagination.nextLink` from a previous response for subsequent pages.

Example request

GET <https://api.folk.app/v1/interactions/upcoming?entity.id=per_55175e81-9a52-4ac3-930e-82792c23499b>

Response `200`

Same structure as List past interactions — a paginated list of Interaction objects.

Errors

400 · 401 · 403 · 404 · 422 · 429 · 500 · 503

Get an interaction

GET /v1/interactions/{interactionId}

Retrieves a single interaction. Full email or calendar body is included when privacy rules allow it.

Path parameters

Parameter	Required	Description
`interactionId`	Yes	The ID of the interaction to retrieve. Can be a logged interaction ID (`lit_…`, 40 chars) or an imported interaction ID (up to 512 chars).

Query parameters

Parameter	Required	Description
`entity.id`	Yes	The person, company, or object linked to the interaction.

Example request

GET <https://api.folk.app/v1/interactions/lit_b049db09-c03d-4f32-96d6-d314760add5d?entity.id=per_55175e81-9a52-4ac3-930e-82792c23499b>

Response `200`

Returns a single Interaction object. For imported email/calendar interactions, content.body contains the full body (only on this endpoint).

Errors

400 · 401 · 403 · 404 · 422 · 429 · 500 · 503

Update an interaction

PATCH /v1/interactions/{interactionId}

Partially update an existing logged interaction (title, content, date-time, activityType). Imported interactions cannot be updated.

Path parameters

Parameter	Required	Description
`interactionId`	Yes	The ID of the logged interaction to update (`lit_…`).

Request body

Field	Type	Required	Description
`entity.id`	string (40 chars)	Yes	The person or company connected to the interaction.
`dateTime`	string (ISO 8601)	No	The date and time of the interaction.
`title`	string (max 255)	No	The title of the interaction.
`content`	string (max 100,000)	No	The multi-line content of the interaction.
`activityType`	string	No	The logged activity type. See Activity types below.

Example request

{   "entity": {     "id": "per_55175e81-9a52-4ac3-930e-82792c23499b"   },   "title": "Updated coffee meeting",   "activityType": "meeting" }

Response `200`

Returns the updated LoggedInteraction.

Errors

400 Bad Request · 401 Unauthorized · 403 Forbidden · 404 Not Found · 422 Unprocessable Entity · 429 Too Many Requests · 500 Internal Server Error · 503 Service Unavailable

Delete an interaction

DELETE /v1/interactions/{interactionId}

Delete an existing logged interaction. Imported interactions cannot be deleted.

Path parameters

Parameter	Required	Description
`interactionId`	Yes	The ID of the logged interaction to delete (`lit_…`).

Query parameters

Parameter	Required	Description
`entity.id`	Yes	The person or company the interaction is linked to.

Example request

DELETE <https://api.folk.app/v1/interactions/lit_b049db09-c03d-4f32-96d6-d314760add5d?entity.id=per_55175e81-9a52-4ac3-930e-82792c23499b>

Response `200`

{   "data": {     "id": "lit_b049db09-c03d-4f32-96d6-d314760add5d"   } }

Errors

400 · 401 · 403 · 404 · 422 · 429 · 500 · 503

Data models

Activity types (logged interactions)

activityType accepts one of:

Predefined activities: call, meeting, message, coffee, lunch, event, drink
Messaging apps: whatsapp, twitter, linkedin, hangout, skype, slack, iMessage, fbMessenger, signal, discord, wechat, telegram, viber
Emoji: any emoji string (e.g. ☕️)
Campaign messages (response only): campaignMessage

LoggedInteraction

A manually logged interaction linked to an entity.

Field	Type	Description
`id`	string	Logged interaction ID (`lit_…`).
`interactionType`	`logged`	Always `logged`.
`from`	object	Who logged the interaction. `type: user` (workspace member) or `type: sender` (email sender).
`to`	object	The linked entity. `type: person` or `type: company`.
`entity`	object	`id`, `entityType` (`person`/`company`), `fullName`.
`dateTime`	string	ISO 8601 date-time.
`title`	string	Interaction title.
`content`	string	Multi-line content.
`privacyLevel`	`sharedFull`	Logged interactions always expose content to authorized users.
`activityType`	string	Activity type (see above).
`type`	string	Deprecated. Use `activityType`.

EmailMessageInteraction

An imported email message linked to an entity.

Field	Type	Description
`id`	string	Imported interaction ID.
`interactionType`	`email`	Always `email`.
`entity`	object	Linked person or company.
`dateTime`	string	ISO 8601 date-time.
`url`	string	null
`privacyLevel`	string	`sharedFull`, `subjectOnly`, `sensitive`, or `internal`.
`from`	object	Sender (`type: email`, `value`, `name`).
`to`	array	Recipients.
`content.subject`	string	Email subject.
`content.snippet`	string	Short preview. Omitted when privacy rules restrict content.
`content.body`	string	Full email body. Only returned by Get an interaction.

CalendarEventInteraction

An imported calendar event. Same structure as email, with interactionType: calendar and optional content.location.

WhatsappMessageInteraction

An imported WhatsApp message (interactionType: whatsapp).

Field	Type	Description
`from` / `to`	object / array	Participants (`type: phone`, `value`, `name`).
`content.text`	string	Message text. Omitted when privacy rules restrict content.
`content.context`	string	Additional context. Omitted when privacy rules restrict content.

Privacy levels (imported interactions)

sharedFull — content fully visible to every workspace member.
subjectOnly — content hidden for other workspace members.
sensitive / internal — visible only to workspace members involved in the conversation.

See the help center article for details.

Pagination

List endpoints use cursor-based pagination via the cursor query parameter. The response includes data.pagination.nextLink with the full URL for the next page. Omit cursor on the first request.

Rate limiting

All endpoints return rate limit headers:

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset
Retry-After (when rate limited)

Interactions API (Private beta)

Overview

Endpoints

Create an interaction

Request body

Example request

Response 200

Errors

List past interactions

Query parameters

Example request

Response 200

Errors

List upcoming interactions

Query parameters

Example request

Response 200

Errors

Get an interaction

Path parameters

Query parameters

Example request

Response 200

Errors

Update an interaction

Path parameters

Request body

Example request

Response 200

Errors

Delete an interaction

Path parameters

Query parameters

Example request

Response 200

Errors

Data models

Activity types (logged interactions)

LoggedInteraction

EmailMessageInteraction

CalendarEventInteraction

WhatsappMessageInteraction

Privacy levels (imported interactions)

Pagination

Rate limiting

Response `200`

Response `200`

Response `200`

Response `200`

Response `200`

Response `200`