Interaction logs

An interaction log records something that happened with a contact, such as a call, a message, or a note, on the contact timeline. Logs are attached to a contact by its contactId.

Interaction types

Each log is either a configured interaction type or a generic system note. Discover the configured types with GET /interaction-types and reference one by its interactionTypeId. For a quick, untyped entry, send "type": "note" instead. Provide one or the other, not both.

Create an interaction log

POST /contacts/{contactId}/interactions records a log. Requires interactions:write. The fields map is a flat key to string map stored on the log, and date defaults to now when omitted.

bash

curl -X POST https://api.craftify.ai/v1/contacts/CR-100042/interactions \
  -H "Authorization: Bearer cfy_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "interactionTypeId": "665f77a1b2c3d4e5f6a7b8c9",
    "note": "Called to confirm appointment",
    "date": "2026-07-18T17:30:00Z",
    "fields": { "Duration": "30m" }
  }'

A 201 response returns the created log:

json

{
  "id": "il_6a7b8c9d0e1f2a3b4c5d6e7f",
  "contactId": "CR-100042",
  "interactionType": { "id": "665f77a1b2c3d4e5f6a7b8c9", "name": "Phone call" },
  "note": "Called to confirm appointment",
  "fields": { "Duration": "30m" },
  "date": "2026-07-18T17:30:00Z",
  "createdAt": "2026-07-18T17:31:04Z"
}

List interaction logs

GET /contacts/{contactId}/interactions returns a contact logs newest first, with cursor pagination. Requires contacts:read. Filters:

Filter	Matches
`interactionTypeId`	Only logs of this interaction type.
`since`	ISO 8601 timestamp; logs at or after this time.
`until`	ISO 8601 timestamp; logs at or before this time.

bash

curl "https://api.craftify.ai/v1/contacts/CR-100042/interactions?since=2026-07-01T00:00:00Z&limit=50" \
  -H "Authorization: Bearer cfy_live_xxx"

Idempotent replay

Supply uniqueIdentifier to make writes safe to retry. The first call with a given identifier creates the log and returns 201. Any later call with the same identifier returns the existing log with 200 instead of creating a duplicate.

Branch on the HTTP status to tell the two apart: 201 means a new log was created, and 200 means this identifier was already recorded and the existing log was returned.

bash

curl -X POST https://api.craftify.ai/v1/contacts/CR-100042/interactions \
  -H "Authorization: Bearer cfy_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "note",
    "note": "Booking confirmed",
    "uniqueIdentifier": "booking-sys-evt-8842"
  }'

Use a stable identifier from your source system, such as an event id, so a replayed delivery maps to the same log every time.

Contacts — the contact a log attaches to.
Webhooks — receive an interaction_log.created event when a log is added.

Interaction logs