---
title: "List interactions"
method: GET
path: "/v1/interactions"
tags: ["Interactions"]
---

# List interactions

`GET /v1/interactions`

## Request

- Base URL: `https://api.folk.app`
- URL: `https://api.folk.app/v1/interactions`
- Auth: HTTP bearer

Retrieves paginated past or upcoming interactions linked to a person, company, or object, optionally filtered by imported interaction type and workspace member.<br/><Warning>This endpoint is currently in open beta. The API surface may change as we iterate based on feedback.</Warning>

## Query parameters

- `cursor` string
- `entity.id` string, required
- `timeframe` 'past' | 'upcoming', required
- `importedTypes` union
  - ''
  - 'email' | 'calendar' | 'whatsapp' | 'call'
  - string[]
- `user.id` union
  - string
  - string[]

## Response `200`

A paginated list of interactions with optional pagination link.

- object
  - `data` object, required
    - `items` Interaction[], required
      - union: An interaction linked to an entity. Can be imported (email, calendar, WhatsApp, call) or manually logged.
        - EmailMessageInteraction: An imported email message linked to an entity.
          - `id` string, required
          - `entity` object, required: The entity connected to the interaction.
            - `entityType` 'person' | 'company', required: The type of the entity connected to the interaction. Can be `person` or `company`.
            - `id` string, required: The ID of the entity connected to the interaction.
            - `fullName` string, required: The full name of the entity connected to the interaction.
          - `dateTime` string, date-time, required: The date and time of the interaction.
          - `url` string, uri, nullable, required: A link to open the interaction in the original source, when available.
          - `privacyLevel` 'sharedFull' | 'subjectOnly' | 'sensitive' | 'internal', required: 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)
          - `interactionType` 'email', required: The interaction is an imported email message.
          - `from` object, required
            - `type` 'email', required
            - `value` string, required: The email address of the participant.
            - `name` string: 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.
            - `picture` string: The picture URL of the matching workspace member or person, if any.
            - `userId` string: The workspace member this participant resolves to, if any.
          - `to` object[], required: The recipients of the email.
            - `type` 'email', required
            - `value` string, required: The email address of the participant.
            - `name` string: 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.
            - `picture` string: The picture URL of the matching workspace member or person, if any.
            - `userId` string: The workspace member this participant resolves to, if any.
          - `content` object, required
            - `subject` string, required: The subject of the email or calendar event.
            - `snippet` string: A short preview of the interaction content. Omitted when privacy rules restrict content.
            - `location` string: The location of the calendar event, when available.
            - `body` string: The full body of the email or calendar event. Only returned by the get interaction endpoint.
        - CalendarEventInteraction: An imported calendar event linked to an entity.
          - `id` string, required
          - `entity` object, required: The entity connected to the interaction.
            - `entityType` 'person' | 'company', required: The type of the entity connected to the interaction. Can be `person` or `company`.
            - `id` string, required: The ID of the entity connected to the interaction.
            - `fullName` string, required: The full name of the entity connected to the interaction.
          - `dateTime` string, date-time, required: The date and time of the interaction.
          - `url` string, uri, nullable, required: A link to open the interaction in the original source, when available.
          - `privacyLevel` 'sharedFull' | 'subjectOnly' | 'sensitive' | 'internal', required: 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)
          - `interactionType` 'calendar', required: The interaction is an imported calendar event.
          - `from` object, required
            - `type` 'email', required
            - `value` string, required: The email address of the participant.
            - `name` string: 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.
            - `picture` string: The picture URL of the matching workspace member or person, if any.
            - `userId` string: The workspace member this participant resolves to, if any.
          - `to` object[], required: The attendees of the calendar event.
            - `type` 'email', required
            - `value` string, required: The email address of the participant.
            - `name` string: 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.
            - `picture` string: The picture URL of the matching workspace member or person, if any.
            - `userId` string: The workspace member this participant resolves to, if any.
          - `content` object, required
            - `subject` string, required: The subject of the email or calendar event.
            - `snippet` string: A short preview of the interaction content. Omitted when privacy rules restrict content.
            - `location` string: The location of the calendar event, when available.
            - `body` string: The full body of the email or calendar event. Only returned by the get interaction endpoint.
        - WhatsappMessageInteraction: An imported WhatsApp message linked to an entity.
          - `id` string, required
          - `entity` object, required: The entity connected to the interaction.
            - `entityType` 'person' | 'company', required: The type of the entity connected to the interaction. Can be `person` or `company`.
            - `id` string, required: The ID of the entity connected to the interaction.
            - `fullName` string, required: The full name of the entity connected to the interaction.
          - `dateTime` string, date-time, required: The date and time of the interaction.
          - `url` string, uri, nullable, required: Always null. This kind of interaction has no link to open in its source.
          - `privacyLevel` 'sharedFull' | 'subjectOnly' | 'sensitive' | 'internal', required: 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)
          - `interactionType` 'whatsapp', required: The interaction is an imported WhatsApp message.
          - `from` object, required
            - `type` 'phone', required
            - `value` string, required: The phone number of the participant.
            - `name` string: 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.
            - `picture` string: The picture URL of the matching workspace member or person, if any.
            - `userId` string: The workspace member this participant resolves to, if any.
          - `to` object[], required: The recipients of the WhatsApp message.
            - `type` 'phone', required
            - `value` string, required: The phone number of the participant.
            - `name` string: 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.
            - `picture` string: The picture URL of the matching workspace member or person, if any.
            - `userId` string: The workspace member this participant resolves to, if any.
          - `content` object, required
            - `text` string: The message text. Omitted when privacy rules restrict content.
            - `context` string: Additional context around the message. Omitted when privacy rules restrict content.
        - CallInteraction: A recorded phone call linked to an entity.
          - `id` string, required
          - `entity` object, required: The entity connected to the interaction.
            - `entityType` 'person' | 'company', required: The type of the entity connected to the interaction. Can be `person` or `company`.
            - `id` string, required: The ID of the entity connected to the interaction.
            - `fullName` string, required: The full name of the entity connected to the interaction.
          - `dateTime` string, date-time, required: The date and time of the interaction.
          - `url` string, uri, nullable, required: Always null. This kind of interaction has no link to open in its source.
          - `privacyLevel` 'sharedFull' | 'subjectOnly' | 'sensitive' | 'internal', required: 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)
          - `interactionType` 'call', required: The interaction is a recorded phone call.
          - `from` object, required: The workspace member who placed the call, through their caller ID.
            - `type` 'phone', required
            - `value` string, required: The phone number of the participant.
            - `name` string: 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.
            - `picture` string: The picture URL of the matching workspace member or person, if any.
            - `userId` string: The workspace member this participant resolves to, if any.
          - `to` object[], required: The contact who was called. Always a single participant.
            - `type` 'phone', required
            - `value` string, required: The phone number of the participant.
            - `name` string: 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.
            - `picture` string: The picture URL of the matching workspace member or person, if any.
            - `userId` string: The workspace member this participant resolves to, if any.
          - `content` object, required
            - `status` 'ongoing' | 'processing' | 'completed' | 'missed' | 'failed', required: 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.
            - `duration` integer, required: The duration of the call, in seconds.
            - `summary` string: 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.
            - `transcript` object: 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.
              - …
        - LoggedInteraction: A manually logged interaction linked to an entity.
          - `id` string, required
          - `interactionType` 'logged', required: The interaction is a manually logged interaction.
          - `from` union, required: Who logged the interaction. Can be a workspace user or an email sender.
            - object
              - …
            - object
              - …
          - `to` object, required: The entity the interaction is linked to.
            - `type` union, required: The type of the entity the interaction is linked to.
              - …
            - `value` string, required: The ID of the person or company the interaction is linked to.
            - `name` string: 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.
            - `picture` string: The picture URL of the matching workspace member or person, if any.
            - `userId` string: The workspace member this participant resolves to, if any.
          - `entity` object, required: The entity connected to the interaction.
            - `entityType` 'person' | 'company', required: The type of the entity connected to the interaction. Can be `person` or `company`.
            - `id` string, required: The ID of the entity connected to the interaction.
            - `fullName` string, required: The full name of the entity connected to the interaction.
          - `dateTime` string, date-time, required: The date and time of the interaction.
          - `title` string, required: The title of the interaction.
          - `content` string, required: The multi-line content of the interaction.
          - `privacyLevel` 'sharedFull', required: Logged interactions always expose their content to authorized users.
          - `type` union, required: Deprecated. Use `activityType` instead.
            - string, emoji: An emoji representing the interaction type.
            - 'campaignMessage': A campaign message sent via folk.
            - string: A predefined interaction type. Known values may grow over time; clients should handle unknown values.
            - string: A messaging app used for the interaction. Known values may grow over time; clients should handle unknown values.
          - `activityType` union, required: The logged activity type. Can be a predefined activity, a messaging app, or an emoji.
            - string, emoji: An emoji representing the interaction type.
            - 'campaignMessage': A campaign message sent via folk.
            - string: A predefined interaction type. Known values may grow over time; clients should handle unknown values.
            - string: A messaging app used for the interaction. Known values may grow over time; clients should handle unknown values.
    - `pagination` object, required
      - `nextLink` string
  - `deprecations` string[]

## Other responses

- `400`: The request was unacceptable, often due to missing an invalid parameter.
- `401`: No valid API key provided.
- `403`: The API key doesn’t have permissions to perform the request.
- `404`: The requested resource doesn’t exist.
- `422`: The request was unacceptable, often due to missing or invalid parameters.
- `429`: Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
- `500`: Something went wrong on our end.
- `503`: The server is overloaded or down for maintenance.

## Changes

- **2026-11-03** `c6818f3ba60d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/folk/apis/folk-external-api/changes/v1/interactions/get.md)

---

[API](https://skmtc.dev/folk/apis/folk-external-api.md) - [All operations](https://skmtc.dev/folk/apis/folk-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/folk/apis/folk-external-api/revisions/c6818f3ba60d?raw)