# Send a sales enquiry to Ownrecord

> The leads.create operation: POST /api/v1/public/{brandSlug}/leads in the REST API and the leads_create tool in the MCP server.

Records a sales enquiry for Ownrecord itself (the /contact form of ownrecord.io) and emails it to Ownrecord's
sales team. It works only on the platform brand (`ownrecord`); any other brand slug answers `resource_not_found`.

The enquiry keeps the name, email, company, a monthly volume range, the optional message, the page it was sent
from and what the visitor agreed to: `consent.contact` (required, Ownrecord may use the details to answer) and
`consent.marketing` (optional opt-in to product updates), with the version of the consent text. No IP address is
stored.

Requests are limited per client IP (5 an hour) and per address (3 a day), whether or not they succeed
(`rate_limited`). The website form also has a honeypot field and drops what bots send before calling this.

Public: the website calls it, no API key needed.

## At a glance

- **REST:** `POST /api/v1/public/{brandSlug}/leads`
- **MCP tool:** `leads_create`
- **Operation ID:** `leads.create`
- **Scope:** Brand
- **Permission:** `customers:write`
- **Risk tier:** `write`
- **Dry run:** Not supported
- **Idempotency:** `Idempotency-Key` required
- **Modes:** Test and live
- **Authentication:** None (a public endpoint, rate-limited per IP address)
- **Since:** M12

## Request

### Path parameters

| Field       | Type   | Description                                                                     |
| ----------- | ------ | ------------------------------------------------------------------------------- |
| `brandSlug` | string | The platform brand's slug (`ownrecord`): leads belong to Ownrecord's own brand. |

### Body

A JSON object (`Content-Type: application/json`):

| Field               | Type                                                                       | Required | Description                                                                                                                                   |
| ------------------- | -------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`              | string                                                                     | Yes      | The person to answer.                                                                                                                         |
| `email`             | string                                                                     | Yes      | Where sales answers.                                                                                                                          |
| `company`           | string                                                                     | Yes      | The company the request is for.                                                                                                               |
| `volumeRange`       | one of `not_live_yet`, `under_30k`, `30k_to_175k`, `175k_to_1m`, `over_1m` | Yes      | Monthly live volume, roughly.                                                                                                                 |
| `message`           | string                                                                     | No       | What the request is about (optional).                                                                                                         |
| `sourcePage`        | string                                                                     | Yes      | The site page the form was sent from, e.g. `/contact`.                                                                                        |
| `consent`           | object                                                                     | Yes      | `contact` must be true: the visitor agrees that Ownrecord uses the details to answer. `marketing` opts in to product updates (default false). |
| `consent.contact`   | `true`                                                                     | Yes      |                                                                                                                                               |
| `consent.marketing` | boolean                                                                    | No       |                                                                                                                                               |

## Response

`201 Created` with a JSON object:

| Field       | Type        | Description               |
| ----------- | ----------- | ------------------------- |
| `object`    | `"lead"`    |                           |
| `id`        | `lead_…` ID |                           |
| `createdAt` | date-time   |                           |
| `message`   | string      | What to tell the visitor. |

## Examples

### Ask sales about Enterprise

```http
POST /api/v1/public/ownrecord/leads
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14
Content-Type: application/json

{
  "name": "Ana Kovač",
  "email": "ana@example.com",
  "company": "Acme Digital d.o.o.",
  "volumeRange": "175k_to_1m",
  "message": "We run two brands from two EU entities and want to talk about Enterprise.",
  "sourcePage": "/contact",
  "consent": {
    "contact": true,
    "marketing": false
  }
}
```

Response (`201`):

```json
{
  "object": "lead",
  "id": "lead_01m4tx5nj8emwbyf7y9vcf48c0",
  "createdAt": "2026-10-26T09:30:00.000Z",
  "message": "Thanks. We've received your request and will answer at ana@example.com."
}
```

## Errors

| Code                                                                                     | HTTP status | When                                                                                                                                                                                       | What to do                                                                                           |
| ---------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
| [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed)   | 400         | A field is missing or malformed: an empty name or company, an email that isn't an address, an unknown `volumeRange`, a `sourcePage` that isn't a site path, or `consent.contact` not true. | Fix the fields listed in `details.issues` and send the request again.                                |
| [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found) | 404         | `brandSlug` isn't the platform brand (leads exist only on Ownrecord's own brand).                                                                                                          | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode. |
| [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited)             | 429         | Too many enquiries from this client IP (5 an hour) or for this address (3 a day); wait `retry_after_ms`.                                                                                   | Wait for `retry_after_ms` and retry with backoff.                                                    |

It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`invalid_json`](https://ownrecord.io/docs/reference/errors.md#invalid_json), [`unsupported_media_type`](https://ownrecord.io/docs/reference/errors.md#unsupported_media_type), [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required), [`idempotency_key_required`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_required), [`idempotency_key_reused`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_reused), [`idempotency_in_progress`](https://ownrecord.io/docs/reference/errors.md#idempotency_in_progress), [`dry_run_not_supported`](https://ownrecord.io/docs/reference/errors.md#dry_run_not_supported), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).