> ## 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.
# (Beta) List interactions
> Retrieves paginated past or upcoming interactions linked to a person, company, or object, optionally filtered by imported interaction type and workspace member.
This endpoint is currently in open beta. The API surface may change as we iterate based on feedback.
## OpenAPI
````yaml /schemas/2025-06-09.json get /v1/interactions
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: Credits
description: Operations related to credits.
- name: Deals
description: Operations related to deals.
- name: Groups
description: Operations related to groups.
- name: Group members
description: Operations related to group members.
- name: Group custom fields
description: Operations related to group custom fields.
- 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/interactions:
get:
tags:
- Interactions
summary: List interactions
description: >-
Retrieves paginated past or upcoming interactions linked to a person,
company, or object, optionally filtered by imported interaction type and
workspace member.
This endpoint is currently in open beta.
The API surface may change as we iterate based on feedback.
operationId: listInteractions
parameters:
- schema:
type: string
maxLength: 512
required: false
description: >-
A cursor for pagination across multiple pages of results. Don’t
include this parameter on the first call. Use the
`pagination.nextLink` value returned in a previous response to
request subsequent results.
example: eyJvZmZzZXQiOjN9
name: cursor
in: query
- schema:
type: string
minLength: 40
maxLength: 40
required: true
description: The person, company, or object linked to interactions.
example: per_55175e81-9a52-4ac3-930e-82792c23499b
name: entity.id
in: query
- schema:
type: string
enum:
- past
- upcoming
required: true
description: >-
Whether to list past interactions (most recent first) or upcoming
interactions.
example: past
name: timeframe
in: query
- schema:
anyOf:
- type: string
enum:
- ''
- type: string
enum:
- email
- calendar
- whatsapp
- call
- type: array
items:
type: string
enum:
- email
- calendar
- whatsapp
- call
minItems: 1
maxItems: 4
required: false
description: >-
The imported interaction types to include. Repeat the parameter to
pass several types. Omit to return every imported type. Pass an
empty value (`importedTypes=`) to return only logged interactions.
Logged interactions are always returned.
example: email
style: form
explode: true
name: importedTypes
in: query
- schema:
anyOf:
- type: string
minLength: 40
maxLength: 40
- type: array
items:
type: string
minLength: 40
maxLength: 40
minItems: 1
maxItems: 50
required: false
description: >-
Only return interactions of these workspace members. Repeat the
parameter to pass several users.
example: usr_55175e81-9a52-4ac3-930e-82792c23499b
style: form
explode: true
name: user.id
in: query
responses:
'200':
description: A paginated list of interactions with optional pagination link.
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'
X-RateLimit-Limit-Burst:
$ref: '#/components/headers/X-RateLimit-Limit-Burst'
X-RateLimit-Remaining-Burst:
$ref: '#/components/headers/X-RateLimit-Remaining-Burst'
X-RateLimit-Reset-Burst:
$ref: '#/components/headers/X-RateLimit-Reset-Burst'
RateLimit-Policy:
$ref: '#/components/headers/RateLimit-Policy'
RateLimit:
$ref: '#/components/headers/RateLimit'
Retry-After:
$ref: '#/components/headers/Retry-After'
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/Interaction'
pagination:
type: object
properties:
nextLink:
type: string
required:
- items
- pagination
example:
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
Discussed the new project.
type: coffee
activityType: coffee
pagination:
nextLink: >-
https://api.folk.app/v1/interactions?timeframe=past&entity.id=per_55175e81-9a52-4ac3-930e-82792c23499b&cursor=eyJmb28iOiJiYXIifQ%3D%3D
deprecations:
type: array
items:
type: string
example:
- This field is deprecated
required:
- data
example:
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
Discussed the new project.
type: coffee
activityType: coffee
pagination:
nextLink: >-
https://api.folk.app/v1/interactions?timeframe=past&entity.id=per_55175e81-9a52-4ac3-930e-82792c23499b&cursor=eyJmb28iOiJiYXIifQ%3D%3D
'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.
X-RateLimit-Limit-Burst:
schema:
type: integer
example: 20
description: >-
The maximum number of requests that you can make in the current burst
rate limit window.
X-RateLimit-Remaining-Burst:
schema:
type: integer
example: 18
description: The number of requests remaining in the current burst rate limit window.
X-RateLimit-Reset-Burst:
schema:
type: integer
example: 1747322902
description: >-
The time at which the current burst rate limit window resets, in UTC
epoch seconds.
RateLimit-Policy:
schema:
type: string
example: '"default";q=600;w=60, "burst";q=20;w=2'
description: >-
The rate limit policies applied to the request, as defined by the IETF
RateLimit header fields draft. `q` is the number of requests allowed per
window and `w` the window length in seconds.
RateLimit:
schema:
type: string
example: '"default";r=598;t=42, "burst";r=18;t=1'
description: >-
The current usage of each rate limit policy, as defined by the IETF
RateLimit header fields draft. `r` is the number of requests remaining
and `t` the number of seconds until the window resets.
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:
Interaction:
anyOf:
- $ref: '#/components/schemas/EmailMessageInteraction'
- $ref: '#/components/schemas/CalendarEventInteraction'
- $ref: '#/components/schemas/WhatsappMessageInteraction'
- $ref: '#/components/schemas/CallInteraction'
- $ref: '#/components/schemas/LoggedInteraction'
description: >-
An interaction linked to an entity. Can be imported (email, calendar,
WhatsApp, call) or manually logged.
example:
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
Discussed the new project.
type: coffee
activityType: coffee
EmailMessageInteraction:
type: object
properties:
id:
type: string
minLength: 1
maxLength: 512
entity:
type: object
properties:
entityType:
type: string
enum:
- person
- company
description: >-
The type of the entity connected to the interaction. Can be
`person` or `company`.
example: person
id:
type: string
minLength: 40
maxLength: 40
description: The ID of the entity connected to the interaction.
example: per_55175e81-9a52-4ac3-930e-82792c23499b
fullName:
type: string
description: The full name of the entity connected to the interaction.
example: John Doe
required:
- entityType
- id
- fullName
description: The entity connected to the interaction.
dateTime:
type: string
format: date-time
description: The date and time of the interaction.
example: '2025-07-17T09:00:00.000Z'
url:
type:
- string
- 'null'
format: uri
description: >-
A link to open the interaction in the original source, when
available.
example: https://mail.google.com/mail/u/0/#inbox/abc123
privacyLevel:
type: string
enum:
- sharedFull
- subjectOnly
- sensitive
- internal
description: >
Interaction privacy level:
- `**sharedFull` means the interaction content is fully visible to
every workspace member.
- `**subjectOnly` means the interacton content is hidden for other
workspace members.
- `**sensitve`/`internal` means the interaction is visible only to
the workspace members involved in the conversation.
For more information about interaction privacy, see our [help center
article](https://help.folk.app/en/articles/13056598-security-internal-and-sensitive-interactions)
example: sharedFull
interactionType:
type: string
enum:
- email
description: The interaction is an imported email message.
example: email
from:
type: object
properties:
type:
type: string
enum:
- email
value:
type: string
description: The email address of the participant.
example: jane@example.com
name:
type: string
description: >-
The display name of the participant. Falls back to the email
address or phone number. Omitted only on a logged interaction
whose member was deleted or whose person is gone or unnamed.
example: Jane Doe
picture:
type: string
description: >-
The picture URL of the matching workspace member or person, if
any.
example: https://example.com/pictures/jane-doe.png
userId:
type: string
description: The workspace member this participant resolves to, if any.
example: usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c
required:
- type
- value
to:
type: array
items:
type: object
properties:
type:
type: string
enum:
- email
value:
type: string
description: The email address of the participant.
example: jane@example.com
name:
type: string
description: >-
The display name of the participant. Falls back to the email
address or phone number. Omitted only on a logged interaction
whose member was deleted or whose person is gone or unnamed.
example: Jane Doe
picture:
type: string
description: >-
The picture URL of the matching workspace member or person, if
any.
example: https://example.com/pictures/jane-doe.png
userId:
type: string
description: The workspace member this participant resolves to, if any.
example: usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c
required:
- type
- value
description: The recipients of the email.
content:
type: object
properties:
subject:
type: string
description: The subject of the email or calendar event.
example: Project kickoff
snippet:
type: string
description: >-
A short preview of the interaction content. Omitted when privacy
rules restrict content.
example: Looking forward to discussing the roadmap.
location:
type: string
description: The location of the calendar event, when available.
example: Conference room A
body:
type: string
description: >-
The full body of the email or calendar event. Only returned by
the get interaction endpoint.
example: |-
Hi team,
Looking forward to our kickoff meeting.
required:
- subject
required:
- id
- entity
- dateTime
- url
- privacyLevel
- interactionType
- from
- to
- content
description: An imported email message linked to an entity.
example:
id: b049db09-c03d-4f32-96d6-d314760add5d@gmail.com
interactionType: email
entity:
id: per_55175e81-9a52-4ac3-930e-82792c23499b
entityType: person
fullName: John Doe
dateTime: '2025-07-17T09:00:00.000Z'
url: https://mail.google.com/mail/u/0/#inbox/abc123
privacyLevel: sharedFull
from:
type: email
value: jane@example.com
name: Jane Doe
to:
- type: email
value: john@example.com
name: John Doe
content:
subject: Project kickoff
snippet: Looking forward to discussing the roadmap.
CalendarEventInteraction:
type: object
properties:
id:
type: string
minLength: 1
maxLength: 512
entity:
type: object
properties:
entityType:
type: string
enum:
- person
- company
description: >-
The type of the entity connected to the interaction. Can be
`person` or `company`.
example: person
id:
type: string
minLength: 40
maxLength: 40
description: The ID of the entity connected to the interaction.
example: per_55175e81-9a52-4ac3-930e-82792c23499b
fullName:
type: string
description: The full name of the entity connected to the interaction.
example: John Doe
required:
- entityType
- id
- fullName
description: The entity connected to the interaction.
dateTime:
type: string
format: date-time
description: The date and time of the interaction.
example: '2025-07-17T09:00:00.000Z'
url:
type:
- string
- 'null'
format: uri
description: >-
A link to open the interaction in the original source, when
available.
example: https://mail.google.com/mail/u/0/#inbox/abc123
privacyLevel:
type: string
enum:
- sharedFull
- subjectOnly
- sensitive
- internal
description: >
Interaction privacy level:
- `**sharedFull` means the interaction content is fully visible to
every workspace member.
- `**subjectOnly` means the interacton content is hidden for other
workspace members.
- `**sensitve`/`internal` means the interaction is visible only to
the workspace members involved in the conversation.
For more information about interaction privacy, see our [help center
article](https://help.folk.app/en/articles/13056598-security-internal-and-sensitive-interactions)
example: sharedFull
interactionType:
type: string
enum:
- calendar
description: The interaction is an imported calendar event.
example: calendar
from:
type: object
properties:
type:
type: string
enum:
- email
value:
type: string
description: The email address of the participant.
example: jane@example.com
name:
type: string
description: >-
The display name of the participant. Falls back to the email
address or phone number. Omitted only on a logged interaction
whose member was deleted or whose person is gone or unnamed.
example: Jane Doe
picture:
type: string
description: >-
The picture URL of the matching workspace member or person, if
any.
example: https://example.com/pictures/jane-doe.png
userId:
type: string
description: The workspace member this participant resolves to, if any.
example: usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c
required:
- type
- value
to:
type: array
items:
type: object
properties:
type:
type: string
enum:
- email
value:
type: string
description: The email address of the participant.
example: jane@example.com
name:
type: string
description: >-
The display name of the participant. Falls back to the email
address or phone number. Omitted only on a logged interaction
whose member was deleted or whose person is gone or unnamed.
example: Jane Doe
picture:
type: string
description: >-
The picture URL of the matching workspace member or person, if
any.
example: https://example.com/pictures/jane-doe.png
userId:
type: string
description: The workspace member this participant resolves to, if any.
example: usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c
required:
- type
- value
description: The attendees of the calendar event.
content:
type: object
properties:
subject:
type: string
description: The subject of the email or calendar event.
example: Project kickoff
snippet:
type: string
description: >-
A short preview of the interaction content. Omitted when privacy
rules restrict content.
example: Looking forward to discussing the roadmap.
location:
type: string
description: The location of the calendar event, when available.
example: Conference room A
body:
type: string
description: >-
The full body of the email or calendar event. Only returned by
the get interaction endpoint.
example: |-
Hi team,
Looking forward to our kickoff meeting.
required:
- subject
required:
- id
- entity
- dateTime
- url
- privacyLevel
- interactionType
- from
- to
- content
description: An imported calendar event linked to an entity.
example:
id: c149db09-c03d-4f32-96d6-d314760add5e@gmail.com
interactionType: calendar
entity:
id: per_55175e81-9a52-4ac3-930e-82792c23499b
entityType: person
fullName: John Doe
dateTime: '2025-07-18T14:00:00.000Z'
url: https://calendar.google.com/event?eid=abc123
privacyLevel: sharedFull
from:
type: email
value: jane@example.com
name: Jane Doe
to:
- type: email
value: john@example.com
name: John Doe
content:
subject: Weekly sync
location: Conference room A
WhatsappMessageInteraction:
type: object
properties:
id:
type: string
minLength: 1
maxLength: 512
entity:
type: object
properties:
entityType:
type: string
enum:
- person
- company
description: >-
The type of the entity connected to the interaction. Can be
`person` or `company`.
example: person
id:
type: string
minLength: 40
maxLength: 40
description: The ID of the entity connected to the interaction.
example: per_55175e81-9a52-4ac3-930e-82792c23499b
fullName:
type: string
description: The full name of the entity connected to the interaction.
example: John Doe
required:
- entityType
- id
- fullName
description: The entity connected to the interaction.
dateTime:
type: string
format: date-time
description: The date and time of the interaction.
example: '2025-07-17T09:00:00.000Z'
url:
type:
- string
- 'null'
format: uri
description: >-
Always null. This kind of interaction has no link to open in its
source.
privacyLevel:
type: string
enum:
- sharedFull
- subjectOnly
- sensitive
- internal
description: >
Interaction privacy level:
- `**sharedFull` means the interaction content is fully visible to
every workspace member.
- `**subjectOnly` means the interacton content is hidden for other
workspace members.
- `**sensitve`/`internal` means the interaction is visible only to
the workspace members involved in the conversation.
For more information about interaction privacy, see our [help center
article](https://help.folk.app/en/articles/13056598-security-internal-and-sensitive-interactions)
example: sharedFull
interactionType:
type: string
enum:
- whatsapp
description: The interaction is an imported WhatsApp message.
example: whatsapp
from:
type: object
properties:
type:
type: string
enum:
- phone
value:
type: string
description: The phone number of the participant.
example: '+14155552671'
name:
type: string
description: >-
The display name of the participant. Falls back to the email
address or phone number. Omitted only on a logged interaction
whose member was deleted or whose person is gone or unnamed.
example: Jane Doe
picture:
type: string
description: >-
The picture URL of the matching workspace member or person, if
any.
example: https://example.com/pictures/jane-doe.png
userId:
type: string
description: The workspace member this participant resolves to, if any.
example: usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c
required:
- type
- value
to:
type: array
items:
type: object
properties:
type:
type: string
enum:
- phone
value:
type: string
description: The phone number of the participant.
example: '+14155552671'
name:
type: string
description: >-
The display name of the participant. Falls back to the email
address or phone number. Omitted only on a logged interaction
whose member was deleted or whose person is gone or unnamed.
example: Jane Doe
picture:
type: string
description: >-
The picture URL of the matching workspace member or person, if
any.
example: https://example.com/pictures/jane-doe.png
userId:
type: string
description: The workspace member this participant resolves to, if any.
example: usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c
required:
- type
- value
description: The recipients of the WhatsApp message.
content:
type: object
properties:
text:
type: string
description: The message text. Omitted when privacy rules restrict content.
example: Are we still on for tomorrow?
context:
type: string
description: >-
Additional context around the message. Omitted when privacy
rules restrict content.
example: ''
required:
- id
- entity
- dateTime
- url
- privacyLevel
- interactionType
- from
- to
- content
description: An imported WhatsApp message linked to an entity.
example:
id: d249db09-c03d-4f32-96d6-d314760add5f@whatsapp.com
interactionType: whatsapp
entity:
id: per_55175e81-9a52-4ac3-930e-82792c23499b
entityType: person
fullName: John Doe
dateTime: '2025-07-17T10:30:00.000Z'
url: null
privacyLevel: sensitive
from:
type: phone
value: '+14155552671'
name: Jane Doe
to:
- type: phone
value: '+14155559876'
name: John Doe
content:
text: Are we still on for tomorrow?
CallInteraction:
type: object
properties:
id:
type: string
minLength: 1
maxLength: 512
entity:
type: object
properties:
entityType:
type: string
enum:
- person
- company
description: >-
The type of the entity connected to the interaction. Can be
`person` or `company`.
example: person
id:
type: string
minLength: 40
maxLength: 40
description: The ID of the entity connected to the interaction.
example: per_55175e81-9a52-4ac3-930e-82792c23499b
fullName:
type: string
description: The full name of the entity connected to the interaction.
example: John Doe
required:
- entityType
- id
- fullName
description: The entity connected to the interaction.
dateTime:
type: string
format: date-time
description: The date and time of the interaction.
example: '2025-07-17T09:00:00.000Z'
url:
type:
- string
- 'null'
format: uri
description: >-
Always null. This kind of interaction has no link to open in its
source.
privacyLevel:
type: string
enum:
- sharedFull
- subjectOnly
- sensitive
- internal
description: >
Interaction privacy level:
- `**sharedFull` means the interaction content is fully visible to
every workspace member.
- `**subjectOnly` means the interacton content is hidden for other
workspace members.
- `**sensitve`/`internal` means the interaction is visible only to
the workspace members involved in the conversation.
For more information about interaction privacy, see our [help center
article](https://help.folk.app/en/articles/13056598-security-internal-and-sensitive-interactions)
example: sharedFull
interactionType:
type: string
enum:
- call
description: The interaction is a recorded phone call.
example: call
from:
type: object
properties:
type:
type: string
enum:
- phone
value:
type: string
description: The phone number of the participant.
example: '+14155552671'
name:
type: string
description: >-
The display name of the participant. Falls back to the email
address or phone number. Omitted only on a logged interaction
whose member was deleted or whose person is gone or unnamed.
example: Jane Doe
picture:
type: string
description: >-
The picture URL of the matching workspace member or person, if
any.
example: https://example.com/pictures/jane-doe.png
userId:
type: string
description: The workspace member this participant resolves to, if any.
example: usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c
required:
- type
- value
description: The workspace member who placed the call, through their caller ID.
to:
type: array
items:
type: object
properties:
type:
type: string
enum:
- phone
value:
type: string
description: The phone number of the participant.
example: '+14155552671'
name:
type: string
description: >-
The display name of the participant. Falls back to the email
address or phone number. Omitted only on a logged interaction
whose member was deleted or whose person is gone or unnamed.
example: Jane Doe
picture:
type: string
description: >-
The picture URL of the matching workspace member or person, if
any.
example: https://example.com/pictures/jane-doe.png
userId:
type: string
description: The workspace member this participant resolves to, if any.
example: usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c
required:
- type
- value
description: The contact who was called. Always a single participant.
content:
type: object
properties:
status:
type: string
enum:
- ongoing
- processing
- completed
- missed
- failed
description: >-
The status of the call. `ongoing`: the call is ringing or in
progress. `processing`: the call has ended and its summary is
still being produced. `completed`: the call is over and fully
processed. `missed`: the contact did not answer, was busy, or
the call was cancelled. `failed`: the call could not be placed
or connected.
example: completed
duration:
type: integer
minimum: 0
description: The duration of the call, in seconds.
example: 312
summary:
type: string
description: >-
The summary of the call. Only returned once the status is
`completed`. Omitted when the call was not recorded, when the
recording could not be processed, and when privacy rules
restrict content.
example: John confirmed the budget and asked for a proposal by Friday.
transcript:
type: object
properties:
language:
type: string
description: >-
The ISO 639-3 code of the language detected during the call,
when available.
example: eng
segments:
type: array
items:
type: object
properties:
speaker:
type: object
properties:
type:
type: string
enum:
- phone
value:
type: string
description: The phone number of the participant.
example: '+14155552671'
name:
type: string
description: >-
The display name of the participant. Falls back to
the email address or phone number. Omitted only on
a logged interaction whose member was deleted or
whose person is gone or unnamed.
example: Jane Doe
picture:
type: string
description: >-
The picture URL of the matching workspace member
or person, if any.
example: https://example.com/pictures/jane-doe.png
userId:
type: string
description: >-
The workspace member this participant resolves to,
if any.
example: usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c
required:
- type
- value
description: >-
The participant who spoke during the segment. A copy
of `from` or of the `to` entry, so match it to a
participant by `value`.
text:
type: string
description: What the speaker said during the segment.
example: Hi John, thanks for taking the call.
start:
type: number
description: >-
When the segment starts, in seconds from the beginning
of the call.
example: 1.2
end:
type: number
description: >-
When the segment ends, in seconds from the beginning
of the call.
example: 3.8
required:
- speaker
- text
- start
- end
description: >-
The transcript of the call, split into speaker-attributed
segments in chronological order.
required:
- segments
description: >-
The diarized transcript of the call. Only returned by the get
interaction endpoint. Omitted when the recording could not be
processed, and when privacy rules restrict content.
required:
- status
- duration
required:
- id
- entity
- dateTime
- url
- privacyLevel
- interactionType
- from
- to
- content
description: A recorded phone call linked to an entity.
example:
id: CA1234567890abcdef1234567890abcdef
interactionType: call
entity:
id: per_55175e81-9a52-4ac3-930e-82792c23499b
entityType: person
fullName: John Doe
dateTime: '2025-07-17T11:00:00.000Z'
url: null
privacyLevel: sharedFull
from:
type: phone
value: '+14155552671'
name: Jane Doe
to:
- type: phone
value: '+14155559876'
name: John Doe
content:
status: completed
duration: 312
summary: John confirmed the budget and asked for a proposal by Friday.
transcript:
language: eng
segments:
- speaker:
type: phone
value: '+14155559876'
name: John Doe
text: Hello?
start: 0.4
end: 0.9
- speaker:
type: phone
value: '+14155552671'
name: Jane Doe
text: Hi John, thanks for taking the call.
start: 1.2
end: 3.8
LoggedInteraction:
type: object
properties:
id:
type: string
interactionType:
type: string
enum:
- logged
description: The interaction is a manually logged interaction.
example: logged
from:
oneOf:
- type: object
properties:
type:
type: string
enum:
- user
description: The interaction was logged by a workspace member.
example: user
value:
type: string
name:
type: string
description: >-
The display name of the participant. Falls back to the email
address or phone number. Omitted only on a logged
interaction whose member was deleted or whose person is gone
or unnamed.
example: Jane Doe
picture:
type: string
description: >-
The picture URL of the matching workspace member or person,
if any.
example: https://example.com/pictures/jane-doe.png
userId:
type: string
description: The workspace member this participant resolves to, if any.
example: usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c
required:
- type
- value
- type: object
properties:
type:
type: string
enum:
- sender
description: >-
The interaction was logged on behalf of an email sender,
such as a campaign message.
example: sender
name:
type: string
description: The display name of the sender.
example: Jane Doe
value:
type: string
description: The email address of the sender.
example: jane@example.com
picture:
type: string
description: >-
The picture URL of the matching workspace member or person,
if any.
example: https://example.com/pictures/jane-doe.png
userId:
type: string
description: The workspace member this participant resolves to, if any.
example: usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c
required:
- type
- name
- value
description: >-
Who logged the interaction. Can be a workspace user or an email
sender.
to:
type: object
properties:
type:
anyOf:
- type: string
enum:
- person
- type: string
enum:
- company
description: The type of the entity the interaction is linked to.
example: person
value:
type: string
minLength: 40
maxLength: 40
description: The ID of the person or company the interaction is linked to.
example: per_55175e81-9a52-4ac3-930e-82792c23499b
name:
type: string
description: >-
The display name of the participant. Falls back to the email
address or phone number. Omitted only on a logged interaction
whose member was deleted or whose person is gone or unnamed.
example: Jane Doe
picture:
type: string
description: >-
The picture URL of the matching workspace member or person, if
any.
example: https://example.com/pictures/jane-doe.png
userId:
type: string
description: The workspace member this participant resolves to, if any.
example: usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c
required:
- type
- value
description: The entity the interaction is linked to.
entity:
type: object
properties:
entityType:
type: string
enum:
- person
- company
description: >-
The type of the entity connected to the interaction. Can be
`person` or `company`.
example: person
id:
type: string
minLength: 40
maxLength: 40
description: The ID of the entity connected to the interaction.
example: per_55175e81-9a52-4ac3-930e-82792c23499b
fullName:
type: string
description: The full name of the entity connected to the interaction.
example: John Doe
required:
- entityType
- id
- fullName
description: The entity connected to the interaction.
dateTime:
type: string
format: date-time
description: The date and time of the interaction.
example: '2025-07-17T09:00:00.000Z'
title:
type: string
description: The title of the interaction.
example: Coffee with John Doe
content:
type: string
description: The multi-line content of the interaction.
example: |-
Had a coffee with John Doe
Discussed the new project.
privacyLevel:
type: string
enum:
- sharedFull
description: Logged interactions always expose their content to authorized users.
example: sharedFull
type:
anyOf:
- type: string
maxLength: 50
format: emoji
description: An emoji representing the interaction type.
example: ☕️
- type: string
enum:
- campaignMessage
description: A campaign message sent via folk.
example: campaignMessage
- type: string
description: >-
A predefined interaction type. Known values may grow over time;
clients should handle unknown values.
example: coffee
x-extensible-enum:
- call
- meeting
- message
- coffee
- lunch
- event
- drink
- type: string
description: >-
A messaging app used for the interaction. Known values may grow
over time; clients should handle unknown values.
example: slack
x-extensible-enum:
- whatsapp
- twitter
- linkedin
- instagram
- hangout
- tiktok
- skype
- slack
- iMessage
- fbMessenger
- signal
- discord
- wechat
- telegram
- viber
description: Deprecated. Use `activityType` instead.
deprecated: true
example: coffee
activityType:
anyOf:
- type: string
maxLength: 50
format: emoji
description: An emoji representing the interaction type.
example: ☕️
- type: string
enum:
- campaignMessage
description: A campaign message sent via folk.
example: campaignMessage
- type: string
description: >-
A predefined interaction type. Known values may grow over time;
clients should handle unknown values.
example: coffee
x-extensible-enum:
- call
- meeting
- message
- coffee
- lunch
- event
- drink
- type: string
description: >-
A messaging app used for the interaction. Known values may grow
over time; clients should handle unknown values.
example: slack
x-extensible-enum:
- whatsapp
- twitter
- linkedin
- instagram
- hangout
- tiktok
- skype
- slack
- iMessage
- fbMessenger
- signal
- discord
- wechat
- telegram
- viber
description: >-
The logged activity type. Can be a predefined activity, a messaging
app, or an emoji.
example: coffee
required:
- id
- interactionType
- from
- to
- entity
- dateTime
- title
- content
- privacyLevel
- type
- activityType
description: A manually logged interaction linked to an entity.
example:
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
title: Coffee with John Doe
content: |-
Had a coffee with John Doe
Discussed the new project.
entity:
id: per_55175e81-9a52-4ac3-930e-82792c23499b
entityType: person
fullName: John Doe
dateTime: '2025-07-17T09:00:00.000Z'
privacyLevel: sharedFull
type: coffee
activityType: coffee
Error:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: TOO_MANY_REQUESTS
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:
policy: burst
limit: 20
remaining: 0
windowSeconds: 2
retryAfter: '2025-10-01T12:00:02.000Z'
required:
- code
- message
- documentationUrl
- requestId
- timestamp
required:
- error
description: Error response containing error details.
RateLimitError:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: TOO_MANY_REQUESTS
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
properties:
policy:
type: string
enum:
- default
- burst
description: The name of the rate limit policy.
limit:
type: integer
description: The maximum number of requests allowed per window.
remaining:
type: integer
description: The number of requests remaining in the current window.
windowSeconds:
type: integer
description: The length of the window, in seconds.
retryAfter:
type: string
format: date-time
description: When the current window resets.
policies:
type: array
items:
type: object
properties:
policy:
type: string
enum:
- default
- burst
description: The name of the rate limit policy.
limit:
type: integer
description: The maximum number of requests allowed per window.
remaining:
type: integer
description: >-
The number of requests remaining in the current
window.
windowSeconds:
type: integer
description: The length of the window, in seconds.
retryAfter:
type: string
format: date-time
description: When the current window resets.
required:
- policy
- limit
- remaining
- windowSeconds
- retryAfter
description: >-
The status of every rate limit policy applied to the
request.
required:
- policy
- limit
- remaining
- windowSeconds
- retryAfter
- policies
description: >-
The exceeded rate limit policy. When several are exceeded, the
one resetting last.
required:
- code
- message
- documentationUrl
- requestId
- timestamp
- details
required:
- error
description: Error response returned when a rate limit is exceeded.
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'
X-RateLimit-Limit-Burst:
$ref: '#/components/headers/X-RateLimit-Limit-Burst'
X-RateLimit-Remaining-Burst:
$ref: '#/components/headers/X-RateLimit-Remaining-Burst'
X-RateLimit-Reset-Burst:
$ref: '#/components/headers/X-RateLimit-Reset-Burst'
RateLimit-Policy:
$ref: '#/components/headers/RateLimit-Policy'
RateLimit:
$ref: '#/components/headers/RateLimit'
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'
X-RateLimit-Limit-Burst:
$ref: '#/components/headers/X-RateLimit-Limit-Burst'
X-RateLimit-Remaining-Burst:
$ref: '#/components/headers/X-RateLimit-Remaining-Burst'
X-RateLimit-Reset-Burst:
$ref: '#/components/headers/X-RateLimit-Reset-Burst'
RateLimit-Policy:
$ref: '#/components/headers/RateLimit-Policy'
RateLimit:
$ref: '#/components/headers/RateLimit'
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'
X-RateLimit-Limit-Burst:
$ref: '#/components/headers/X-RateLimit-Limit-Burst'
X-RateLimit-Remaining-Burst:
$ref: '#/components/headers/X-RateLimit-Remaining-Burst'
X-RateLimit-Reset-Burst:
$ref: '#/components/headers/X-RateLimit-Reset-Burst'
RateLimit-Policy:
$ref: '#/components/headers/RateLimit-Policy'
RateLimit:
$ref: '#/components/headers/RateLimit'
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'
X-RateLimit-Limit-Burst:
$ref: '#/components/headers/X-RateLimit-Limit-Burst'
X-RateLimit-Remaining-Burst:
$ref: '#/components/headers/X-RateLimit-Remaining-Burst'
X-RateLimit-Reset-Burst:
$ref: '#/components/headers/X-RateLimit-Reset-Burst'
RateLimit-Policy:
$ref: '#/components/headers/RateLimit-Policy'
RateLimit:
$ref: '#/components/headers/RateLimit'
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'
X-RateLimit-Limit-Burst:
$ref: '#/components/headers/X-RateLimit-Limit-Burst'
X-RateLimit-Remaining-Burst:
$ref: '#/components/headers/X-RateLimit-Remaining-Burst'
X-RateLimit-Reset-Burst:
$ref: '#/components/headers/X-RateLimit-Reset-Burst'
RateLimit-Policy:
$ref: '#/components/headers/RateLimit-Policy'
RateLimit:
$ref: '#/components/headers/RateLimit'
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'
X-RateLimit-Limit-Burst:
$ref: '#/components/headers/X-RateLimit-Limit-Burst'
X-RateLimit-Remaining-Burst:
$ref: '#/components/headers/X-RateLimit-Remaining-Burst'
X-RateLimit-Reset-Burst:
$ref: '#/components/headers/X-RateLimit-Reset-Burst'
RateLimit-Policy:
$ref: '#/components/headers/RateLimit-Policy'
RateLimit:
$ref: '#/components/headers/RateLimit'
Retry-After:
$ref: '#/components/headers/Retry-After'
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitError'
example:
error:
code: TOO_MANY_REQUESTS
message: You have exceeded your rate limit.
documentationUrl: https://developer.folk.app/api-reference/errors#rate-limiting
requestId: 123e4567-e89b-12d3-a456-426614174000
timestamp: '2025-10-01T12:00:00Z'
details:
policy: burst
limit: 20
remaining: 0
windowSeconds: 2
retryAfter: '2025-10-01T12:00:02.000Z'
policies:
- policy: default
limit: 600
remaining: 412
windowSeconds: 60
retryAfter: '2025-10-01T12:01:00.000Z'
- policy: burst
limit: 20
remaining: 0
windowSeconds: 2
retryAfter: '2025-10-01T12:00:02.000Z'
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
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.