FOfolk
Interactions

Create an interaction

Changed on

Creates a new interaction with a person or a company.

post/v1/interactions

Request

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

Headers

Idempotency-Keystring

A unique key, such as a UUID, that makes retrying this request safe: a retry with the same key and body returns the original response without running the operation again. Keys are kept for 24 hours after the request completes.

Example:8e03978e-40d5-43e8-bc93-6894a57f9324

Request body

dateTimestring date-time required

The date and time of the interaction.

titlestring required

The title of the interaction.

contentstring required

The multi-line content of the interaction.

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.",
  "type": "☕️",
  "activityType": "☕️"
}

Response

The created interaction.

deprecationsstring[]

Example response

{
  "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\nDiscussed 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"
  },
  "deprecations": [
    "This field is deprecated"
  ]
}

Changes

  • c6818f3ba60dRevision changes
    • breaking

      added subschema #1 subschema #2 to the / response property oneOf list for the response status

    • info

      added the new optional header request parameter Idempotency-Key

    • info

      added the new instagram enum value to the request property /

    • info

      added the new instagram enum value to the request property /

    • info

      added the new tiktok enum value to the request property /

    • info

      added the new tiktok enum value to the request property /

    • info

      added the non-success response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added subschema #3 subschema #4 to the / response property anyOf list for the response status

    • info

      added subschema #3 subschema #4 to the / response property anyOf list for the response status

    • info

      removed subschema #2 subschema #3 from the / response property anyOf list for the response status

    • info

      removed subschema #2 subschema #3 from the / response property anyOf list for the response status

    • info

      the response property / became required for the status

    • info

      removed subschema #1 subschema #2 from the / response property oneOf list for the response status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status