# Leads

A lead is one enquiry about one listing, together with the whole conversation
that followed: the buyer's messages, your replies and your private notes.
Reading needs `leads:read`, writing needs `leads:write`; see
[Authentication](https://ydomain.com/docs/api/authentication).

| Method | Path | Ability |
| --- | --- | --- |
| `GET` | `/leads` | `leads:read` |
| `GET` | `/leads/{lead}` | `leads:read` |
| `PATCH` | `/leads/{lead}` | `leads:write` |
| `POST` | `/leads/{lead}/messages` | `leads:write` |

`{lead}` is the lead's UUID.

## The lead object

```json
{
  "id": "01920fc4-7b21-7d90-8e55-9a1c3f7d2b08",
  "status": "new",
  "source": "website",
  "domain": "example.net",
  "sender": {
    "name": "Pieter Jansen",
    "email": "pieter@example.com",
    "company": "Jansen Bouw",
    "phone": null
  },
  "message": "Is this name still available, and is the price negotiable?",
  "offer": {
    "amount": 1500,
    "currency": "EUR"
  },
  "reply_to": "example.net.48217@inboxxa.com",
  "spam_score": 2,
  "created_at": "2026-09-14T11:02:19+00:00",
  "last_message_at": "2026-09-15T08:44:51+00:00"
}
```

- `offer` is `null` when no amount was named. A listing that may not advertise a
  sale never carries one, even if an amount was posted to it.
- `reply_to` is the unique address for this conversation. Mail sent to it lands
  back on this lead, which is how email replies stay in the thread.
- `spam_score` runs 0–10; anything the filter was sure about arrives with status
  `spam` and is kept out of your inbox.
- `messages` is only present on `GET /leads/{lead}`.

### Status

| Value | Meaning |
| --- | --- |
| `new` | Not answered yet |
| `open` | In conversation |
| `negotiating` | Talking about price |
| `sold` | Ended in a sale |
| `lost` | Ended without one |
| `spam` | Filtered out |

### Source

| Value | Came from |
| --- | --- |
| `website` | The listing page on the marketplace |
| `embed` | An embedded form on your own domain |
| `email` | A reply to the lead's own address |
| `api` | Created over the API |
| `manual` | Entered by you in the account area |

## List leads

```bash
curl "https://ydomain.com/api/v1/leads?status=new&domain=example.net" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
```

| Parameter | Default | Notes |
| --- | --- | --- |
| `status` | — | One of the status values above |
| `domain` | — | Full domain name, e.g. `example.net` |
| `per_page` | `25` | Capped at 100 |
| `page` | `1` | |

```json
{
  "data": [
    {
      "id": "01920fc4-7b21-7d90-8e55-9a1c3f7d2b08",
      "status": "new",
      "source": "website",
      "domain": "example.net",
      "sender": { "name": "Pieter Jansen", "email": "pieter@example.com" },
      "offer": { "amount": 1500, "currency": "EUR" },
      "created_at": "2026-09-14T11:02:19+00:00"
    }
  ],
  "links": { "next": null },
  "meta": { "current_page": 1, "last_page": 1, "per_page": 25, "total": 1 }
}
```

Newest first. Poll this if you like, but the `lead.created` webhook is cheaper
and arrives in seconds.

## Read one lead

The single-lead response adds the full thread.

```bash
curl https://ydomain.com/api/v1/leads/01920fc4-7b21-7d90-8e55-9a1c3f7d2b08 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
```

```json
{
  "data": {
    "id": "01920fc4-7b21-7d90-8e55-9a1c3f7d2b08",
    "status": "open",
    "domain": "example.net",
    "sender": { "name": "Pieter Jansen", "email": "pieter@example.com" },
    "messages": [
      {
        "id": "01920fc4-7b30-71d2-a0f4-1e7b9c5d3a21",
        "direction": "inbound",
        "from": "pieter@example.com",
        "to": "example.net.48217@inboxxa.com",
        "subject": "Question about example.net",
        "body_text": "Is this name still available, and is the price negotiable?",
        "body_html": null,
        "delivered_at": null,
        "failed_at": null,
        "created_at": "2026-09-14T11:02:19+00:00"
      },
      {
        "id": "01920fc4-9a11-7c03-9b18-77c2e4d18f55",
        "direction": "outbound",
        "from": "example.net.48217@inboxxa.com",
        "to": "pieter@example.com",
        "subject": "Re: Question about example.net",
        "body_text": "It is available. I can do 1750 EUR.",
        "body_html": "<p>It is available. I can do 1750 EUR.</p>",
        "delivered_at": "2026-09-15T08:44:53+00:00",
        "failed_at": null,
        "created_at": "2026-09-15T08:44:51+00:00"
      }
    ]
  }
}
```

`direction` is `inbound` from the buyer, `outbound` from you, and `note` for a
private note that is never sent to anyone.

## Change the status

```bash
curl -X PATCH https://ydomain.com/api/v1/leads/01920fc4-7b21-7d90-8e55-9a1c3f7d2b08 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"status": "negotiating"}'
```

```json
{
  "data": {
    "id": "01920fc4-7b21-7d90-8e55-9a1c3f7d2b08",
    "status": "negotiating",
    "domain": "example.net"
  }
}
```

`status` is the only field this endpoint accepts. It fires
`lead.status_changed` and `lead.updated`.

## Reply to a lead

The reply is emailed to the buyer from the lead's own address, so their answer
comes back into the same thread. It is stored as an `outbound` message.

```bash
curl -X POST https://ydomain.com/api/v1/leads/01920fc4-7b21-7d90-8e55-9a1c3f7d2b08/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "body": "It is available. I can do 1750 EUR, transfer through ydomain.",
    "subject": "Re: Question about example.net"
  }'
```

| Field | Rules |
| --- | --- |
| `body` | Required, 2–20,000 characters. Basic HTML is allowed and sanitised |
| `subject` | Optional, max 250. Defaults to the thread's subject |

`201 Created`:

```json
{
  "data": {
    "id": "01920fc4-9a11-7c03-9b18-77c2e4d18f55",
    "direction": "outbound",
    "from": "example.net.48217@inboxxa.com",
    "to": "pieter@example.com",
    "subject": "Re: Question about example.net",
    "body_text": "It is available. I can do 1750 EUR, transfer through ydomain.",
    "delivered_at": null,
    "created_at": "2026-09-15T08:44:51+00:00"
  }
}
```

`delivered_at` is filled in once the mail has actually gone out, which is a
moment later; `failed_at` is filled in if it could not be delivered. Replying
fires `lead.replied` and `lead.message_sent`.

The sender name and address of a thread are fixed the first time you reply, in
the account area. After that first reply they no longer change, so the buyer
keeps seeing the same sender.