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.

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

{
  "id": "01920fc4-7b21-7d90-8e55-9a1c3f7d2b08",
  "status": "new",
  "source": "website",
  "domain": "example.net",
  "sender": {
    "name": "Pieter Jansen",
    "email": "[email protected]",
    "company": "Jansen Bouw",
    "phone": null
  },
  "message": "Is this name still available, and is the price negotiable?",
  "offer": {
    "amount": 1500,
    "currency": "EUR"
  },
  "reply_to": "[email protected]",
  "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

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`

{
  "data": [
    {
      "id": "01920fc4-7b21-7d90-8e55-9a1c3f7d2b08",
      "status": "new",
      "source": "website",
      "domain": "example.net",
      "sender": { "name": "Pieter Jansen", "email": "[email protected]" },
      "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.

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

{
  "data": {
    "id": "01920fc4-7b21-7d90-8e55-9a1c3f7d2b08",
    "status": "open",
    "domain": "example.net",
    "sender": { "name": "Pieter Jansen", "email": "[email protected]" },
    "messages": [
      {
        "id": "01920fc4-7b30-71d2-a0f4-1e7b9c5d3a21",
        "direction": "inbound",
        "from": "[email protected]",
        "to": "[email protected]",
        "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": "[email protected]",
        "to": "[email protected]",
        "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

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"}'

{
  "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.

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:

{
  "data": {
    "id": "01920fc4-9a11-7c03-9b18-77c2e4d18f55",
    "direction": "outbound",
    "from": "[email protected]",
    "to": "[email protected]",
    "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.