> ## 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 an interaction

> Creates a new [interaction](https://help.folk.app/en/articles/7012167-log-a-new-interaction) with a person or a company.



## OpenAPI

````yaml /schemas/2025-06-09.json post /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: 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/interactions:
    post:
      tags:
        - Interactions
      summary: Create an interaction
      description: >-
        Creates a new
        [interaction](https://help.folk.app/en/articles/7012167-log-a-new-interaction)
        with a person or a company.
      operationId: createInteraction
      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 interaction. You can link people
                    or companies.
                  example:
                    id: per_55175e81-9a52-4ac3-930e-82792c23499b
                dateTime:
                  type: string
                  maxLength: 24
                  format: date-time
                  description: The date and time of the interaction.
                  example: '2025-07-17T09:00:00.000Z'
                title:
                  type: string
                  maxLength: 255
                  description: The title of the interaction.
                  example: Coffee with John Doe
                content:
                  type: string
                  maxLength: 100000
                  description: The multi-line content of the interaction.
                  example: |-
                    Had a coffee with John Doe
                    Discussed the new project.
                type:
                  anyOf:
                    - type: string
                      maxLength: 50
                      format: emoji
                      description: An emoji representing the interaction type.
                      example: ☕️
                    - type: string
                      enum:
                        - call
                        - meeting
                        - message
                        - coffee
                        - lunch
                        - event
                        - drink
                      description: A predefined interaction type.
                      example: coffee
                    - type: string
                      enum:
                        - whatsapp
                        - twitter
                        - linkedin
                        - hangout
                        - skype
                        - slack
                        - iMessage
                        - fbMessenger
                        - signal
                        - discord
                        - wechat
                        - telegram
                        - viber
                      description: A messaging app used for the interaction.
                      example: slack
                  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:
                        - call
                        - meeting
                        - message
                        - coffee
                        - lunch
                        - event
                        - drink
                      description: A predefined interaction type.
                      example: coffee
                    - type: string
                      enum:
                        - whatsapp
                        - twitter
                        - linkedin
                        - hangout
                        - skype
                        - slack
                        - iMessage
                        - fbMessenger
                        - signal
                        - discord
                        - wechat
                        - telegram
                        - viber
                      description: A messaging app used for the interaction.
                      example: slack
                  description: >-
                    The logged activity type. Can be a predefined activity, a
                    messaging app, or an emoji.
                  example: coffee
              required:
                - entity
                - dateTime
                - title
                - content
              additionalProperties: false
      responses:
        '200':
          description: The created interaction.
          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/LoggedInteraction'
                  deprecations:
                    type: array
                    items:
                      type: string
                    example:
                      - This field is deprecated
                required:
                  - data
              example:
                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
                  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
        '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:
    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 user.
                  example: John Doe
              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
              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 full name of the linked entity.
              example: John Doe
          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:
                - call
                - meeting
                - message
                - coffee
                - lunch
                - event
                - drink
              description: A predefined interaction type.
              example: coffee
            - type: string
              enum:
                - whatsapp
                - twitter
                - linkedin
                - hangout
                - skype
                - slack
                - iMessage
                - fbMessenger
                - signal
                - discord
                - wechat
                - telegram
                - viber
              description: A messaging app used for the interaction.
              example: slack
            - type: string
              enum:
                - campaignMessage
              description: A campaign message sent via folk.
              example: campaignMessage
          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:
                - call
                - meeting
                - message
                - coffee
                - lunch
                - event
                - drink
              description: A predefined interaction type.
              example: coffee
            - type: string
              enum:
                - whatsapp
                - twitter
                - linkedin
                - hangout
                - skype
                - slack
                - iMessage
                - fbMessenger
                - signal
                - discord
                - wechat
                - telegram
                - viber
              description: A messaging app used for the interaction.
              example: slack
            - type: string
              enum:
                - campaignMessage
              description: A campaign message sent via folk.
              example: campaignMessage
          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: 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

````