Getting started

This quickstart takes you from zero to your first contact and interaction log. Every request uses the production base URL https://api.craftify.ai/v1 and a key placeholder cfy_live_xxx. Replace it with the key you create in step 1.

Step 1: Create an API key

In the CraftifyAI web app, go to Settings, then Developer API. Create a key, choose the scopes it needs (contacts:read, contacts:write, interactions:write, webhooks:manage), and copy the key. The key is shown only once and stored hashed, so save it somewhere secure right away. If you lose it, revoke it and create a new one.

The Developer API page is available to project owners and managers. If you do not see it under Settings, ask an owner or manager on your project to create a key for you.

Step 2: Verify the key with GET /ping

Confirm the key works and see which project and scopes it carries. Any valid key is accepted here, and no scope is required.

bash

curl https://api.craftify.ai/v1/ping \
  -H "Authorization: Bearer cfy_live_xxx"

Response:

json

{
  "projectId": "5f8a1c2b3d4e5f6a7b8c9d0e",
  "projectName": "Acme Studio",
  "keyName": "Booking system sync",
  "scopes": ["contacts:read", "contacts:write", "interactions:write", "webhooks:manage"]
}

Step 3: Discover reference ids

Contact types, custom fields, and interaction types are configured per project and addressed by id. List them so you know which ids to send. The same pattern works for /interaction-types and /tags.

bash

curl https://api.craftify.ai/v1/contact-types \
  -H "Authorization: Bearer cfy_live_xxx"

curl https://api.craftify.ai/v1/custom-fields \
  -H "Authorization: Bearer cfy_live_xxx"

Step 4: Create a contact

Create a contact with a minimal body. This endpoint always creates and never silently updates, so check for duplicates first if that matters (see Contacts). When you omit contactTypeId, the project default Customer type is used.

bash

curl -X POST https://api.craftify.ai/v1/contacts \
  -H "Authorization: Bearer cfy_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "lastName": "Nguyen",
    "email": "jane@example.com",
    "phone": "+16045551234"
  }'

A 201 response returns the created contact:

json

{
  "contactId": "CR-100042",
  "identityType": "personal",
  "firstName": "Jane",
  "lastName": "Nguyen",
  "email": "jane@example.com",
  "phone": "+16045551234",
  "createdAt": "2026-07-18T17:30:00Z",
  "updatedAt": "2026-07-18T17:30:00Z"
}

Step 5: Add an interaction log

Record something that happened with the contact on its timeline. Use a configured interactionTypeId from step 3, or send "type": "note" for a generic note.

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": "Called to confirm appointment",
    "date": "2026-07-18T17:35:00Z"
  }'

Step 6: List contacts

Find contacts by filter. Here we look one up by email, which matches case-insensitively.

bash

curl "https://api.craftify.ai/v1/contacts?email=jane@example.com" \
  -H "Authorization: Bearer cfy_live_xxx"

List responses are paginated as { data, pagination: { nextCursor, hasMore } }. Pass ?limit= (default 25, max 100) and ?cursor= to page through results.

Next steps

Authentication — key format, header options, and scopes.
Contacts — the full contact model, custom fields, and deduplication.
Interaction logs — idempotent replay with uniqueIdentifier.
Webhooks — receive events instead of polling.
Rate limits & errors — limits, retries, and the error envelope.