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

# Leads

> Create partner leads (inventory leads) in the AnyHouse platform

## Overview

The Leads API allows partners to send **inventory leads** into the AnyHouse platform.

These leads represent potential buyers or renters that can later be offered to brokers through the AnyHouse ecosystem.

When using this endpoint:

* The lead is created with **`source = bought`**
* The lead is **not attached to a listing**
* The lead is **not attached to a broker or agency**
* Customer data is stored separately from the lead

This endpoint is designed for **lead generation partners, portals, and integrations** that send new contacts into the AnyHouse lead inventory.

***

## Endpoint

**POST**

```
/api/partner/leads
```

Example request:

```
POST https://anyhouse.app/api/partner/leads
```

***

## Authentication

You can authenticate using **either** of the following methods.

<Columns cols={2}>
  <Card title="Bearer Token" icon="key">
    Use the standard Authorization header.
  </Card>

  <Card title="X-Api-Key" icon="badge-check">
    Use your partner API key.
  </Card>
</Columns>

### Option 1 — Bearer Token

```
Authorization: Bearer YOUR_API_TOKEN
```

### Option 2 — Partner API Key

```
X-Api-Key: YOUR_PARTNER_API_KEY
```

***

## Required Fields

At least **one** of the following fields must be present:

* `email`
* `phone`

If both are missing, the request will fail validation.

***

## Request Body

```json theme={null}
{
  "name": "John Doe",
  "email": "john@example.com",
  "phone": "+1 809 555 1234",
  "notes": "Interested in Punta Cana properties around $200k.",
  "lead_type": "hot",
  "previous_conversation": [
    {
      "date": "2026-03-01T15:45:00Z",
      "direction": "inbound",
      "from": "john@example.com",
      "to": "sales@partner.com",
      "subject": "Interested in property",
      "body": "Hi, I'm looking for a 2 bedroom apartment in Punta Cana."
    },
    {
      "date": "2026-03-01T16:10:00Z",
      "direction": "outbound",
      "from": "sales@partner.com",
      "to": "john@example.com",
      "subject": "Re: Interested in property",
      "body": "Sure — what is your budget?"
    }
  ]
}
```

***

## Field Description

| Field                  | Type   | Description                                         |
| ---------------------- | ------ | --------------------------------------------------- |
| name                   | string | Contact name                                        |
| email                  | string | Email address (required if phone is not provided)   |
| phone                  | string | Phone number (required if email is not provided)    |
| notes                  | string | Optional notes about the contact                    |
| lead\_type             | string | `"hot"` or `"cold"` lead classification             |
| previous\_conversation | array  | Optional conversation history such as email threads |

***

## Example Success Response

```json theme={null}
{
  "id": 12345,
  "name": "John Doe",
  "email": "john@example.com",
  "phone": "+1 809 555 1234",
  "lead_type": "hot",
  "created_at": "2026-03-03T12:00:00Z"
}
```

***

## Validation Errors

If neither **email** nor **phone** is provided:

```json theme={null}
{
  "message": "The given data was invalid.",
  "errors": {
    "email": [
      "Email is required when phone is missing."
    ],
    "phone": [
      "Phone is required when email is missing."
    ]
  }
}
```

***

## When to Use This Endpoint

Use this endpoint when:

* You are sending **lead inventory into AnyHouse**
* The lead is **not tied to a specific listing**
* You want to attach **contact data and conversation context**
* Leads will later be distributed to brokers inside the platform