> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notealy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Create a contact via the API and have an automation greet them by email — five minutes end to end.

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:

```bash theme={null}
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

1. 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
2. Activate the automation.

## 3. Get the tag id from the API

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
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):

```json theme={null}
{
  "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](/authentication) for scope details.
* Read [Webhooks](/webhooks/overview) to receive events back from Notealy.
* Browse the [API Reference](/api-reference) for every endpoint.