Quickstart

This walk-through wires up the most common public API integration: a website lead form posts to Notealy, the new contact is tagged, and an automation reacts to that tag by sending a templated email.

1. Issue an API token

Settings → API Tokens → New token. Pick scopes people:write, tags:read and tags:write. Copy the token (you will see it once). Confirm the token works:

curl https://thanos.notealy.com/v1/me \
  -H "Authorization: Bearer sk_live_..."

A 200 with your organization details means you are good to go.

2. Set up the automation in the dashboard

Go to Automations → New and configure:
- Trigger: Tag added → select (or create) the tag web-lead
- Action: Send message → channel Email → pick (or create) an email template
Activate the automation.

3. Get the tag id from the API

curl https://thanos.notealy.com/v1/tags \
  -H "Authorization: Bearer sk_live_..." \
  | jq '.[] | select(.name=="web-lead")'

If the tag does not exist yet, create it:

curl -X POST https://thanos.notealy.com/v1/tags \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "web-lead" }'

4. Push a contact with the tag

curl -X POST https://thanos.notealy.com/v1/people \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "phone": "+15555550101",
    "channel": "WEB",
    "tagIds": ["<web-lead-tag-id>"]
  }'

Response (truncated):

{
  "id": "01J...",
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "phone": "+15555550101",
  "channel": "WEB",
  "source": "API",
  "tags": [
    { "id": "<tag-id>", "name": "web-lead", "color": "#88DD00" }
  ],
  "createdAt": "2026-05-04T18:21:00.000Z"
}

The API:

Upserts the contact (matches by phone, then email, then externalId).
Attaches the web-lead tag, emitting contact.tag_added once per newly attached tag.
That event triggers the automation; the email goes out within seconds.

5. Replay safely

Posting the same payload again is safe:

The contact is matched by email and updated, not duplicated.
The tag is already attached, so no new contact.tag_added event is emitted and the automation does not run twice.

This makes the endpoint suitable for retries and at-least-once delivery from your form backend.

What’s next

See Authentication for scope details.
Read Webhooks to receive events back from Notealy.
Browse the API Reference for every endpoint.

Get started

Use cases

Concepts

Webhooks

1. Issue an API token

2. Set up the automation in the dashboard

3. Get the tag id from the API

4. Push a contact with the tag

5. Replay safely

What’s next

​1. Issue an API token

​2. Set up the automation in the dashboard

​3. Get the tag id from the API

​4. Push a contact with the tag

​5. Replay safely

​What’s next

1. Issue an API token

2. Set up the automation in the dashboard

3. Get the tag id from the API

4. Push a contact with the tag

5. Replay safely

What’s next