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

# Leads pipeline

> Track inbound enterprise inquiries, manage lead status, and convert qualified leads into onboarded tenants.

The leads pipeline in the platform console tracks inbound enterprise and government inquiries from first contact through to tenant onboarding. Use it to view new leads, update their status as conversations progress, export the pipeline to CSV, and convert qualified leads into fully onboarded Truthlocks tenants.

<Info>
  The leads pipeline tracks **inbound** inquiries — people who come to you. It is separate from the [AI CMO](/guides/ai-cmo) outbound leads, which are discovered and managed by automated campaigns. The two systems use different status models and different console pages.
</Info>

## Prerequisites

* Platform administrator access to the [console](https://console.truthlocks.com)

## How leads enter the pipeline

Leads are created automatically when a prospect submits an inquiry through the Truthlocks website contact form or another integrated intake channel. Each lead captures the contact's name, email, company, original message, and the source of the inquiry (for example, `website` or `referral`). New leads appear in the pipeline with a status of `new` and are ready for review.

<Tip>
  You can also [create a lead via the API](/api-reference/leads/create) to add contacts from CRM imports, partner referrals, or internal tooling. Leads created through the API enter the pipeline with a status of `new`, just like form submissions.
</Tip>

## Lead lifecycle

Every lead moves through four statuses:

| Status      | Description                                                           |
| :---------- | :-------------------------------------------------------------------- |
| `new`       | A fresh inquiry that has not been reviewed yet                        |
| `contacted` | You have responded to the lead but qualification is still in progress |
| `qualified` | The lead meets your criteria and is ready for onboarding              |
| `archived`  | The lead is no longer active — closed, disqualified, or converted     |

Transition a lead between statuses from the lead detail page or via the API. There are no enforced ordering rules — you can move a lead to any status at any time.

## Viewing the pipeline

Open **Leads** in the platform console. The page displays a searchable, paginated table of all institutional leads. Each row shows:

| Column  | Description                                                |
| :------ | :--------------------------------------------------------- |
| Name    | First and last name of the contact                         |
| Email   | Contact email address                                      |
| Company | Organization name, if provided                             |
| Source  | Where the inquiry originated (e.g. website form, referral) |
| Status  | Current lifecycle status with a color-coded badge          |
| Date    | When the lead was created                                  |

Use the search bar to filter by name, company, or email. Click any lead to open the detail page.

## Lead detail

The detail page shows full contact information — name, email, company, source, and the original inquiry message — along with a timeline of status changes. From this page you can:

* **Update status** — move the lead to `contacted`, `qualified`, or `archived`
* **Convert to tenant** — send an enterprise onboarding invite to the lead's email (see [converting a lead](#converting-a-lead) below)

## Converting a lead

When a lead is qualified and ready to onboard, click **Convert / Onboard Customer** on the lead detail page. This triggers an enterprise onboarding invite email to the lead's contact address. The recipient receives a branded invitation with a link to the [console onboarding wizard](/guides/console-onboarding), where they can set up their organization, issuer, and signing keys.

After conversion, the lead is marked as `qualified`. The new tenant follows the standard [onboarding flow](/guides/onboarding).

<Info>
  The same onboarding invite is sent when a platform admin creates a tenant with the `GOVERNMENT` type. See the [B2G procurement pack](/packs/enterprise/b2g-procurement) for details on the government onboarding flow.
</Info>

## Capturing leads from your website

Use the public lead-capture endpoint to send inquiries from a contact form on your website directly into the leads pipeline. This endpoint does not require authentication, so you can call it from a client-side form without exposing API keys.

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/public/leads \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com",
    "company": "Acme Corp",
    "message": "Interested in enterprise attestation for our compliance workflow.",
    "source": "website"
  }'
```

| Field        | Type   | Required | Description                                      |
| :----------- | :----- | :------- | :----------------------------------------------- |
| `first_name` | string | yes      | Contact first name                               |
| `last_name`  | string | yes      | Contact last name                                |
| `email`      | string | yes      | Contact email address                            |
| `message`    | string | yes      | The inquiry message                              |
| `company`    | string | no       | Organization name                                |
| `source`     | string | no       | Where the inquiry originated (defaults to `www`) |
| `_gotcha`    | string | no       | Honeypot field for spam prevention — see below   |

On success the endpoint returns HTTP 201 with the new lead's `id`.

### Spam prevention

The endpoint includes a hidden honeypot field called `_gotcha`. Add it as a hidden input in your HTML form. Legitimate users leave it empty, but automated bots tend to fill every field. If `_gotcha` contains a value, the request is silently discarded — the server returns a fake 201 success so the bot does not retry.

```html theme={null}
<!-- Hidden honeypot — do not show to users -->
<input type="hidden" name="_gotcha" value="" />
```

### Rate limiting

The public endpoint enforces a rate limit of **3 submissions per IP address per hour**. If a client exceeds this limit, the server responds with HTTP 429 and a `Retry-After` header indicating when the next request will be accepted. This protects the pipeline from abuse without affecting normal form submissions.

## Exporting the pipeline

Click **Export Pipeline** on the leads page to download a CSV containing all leads. The export includes ID, first name, last name, email, company, source, status, and creation date.

## Managing leads via the API

### Create a lead

Add a single lead to the pipeline. Requires platform administrator authentication.

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/platform/leads \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@acme.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "company": "Acme Corp",
    "title": "VP of Engineering",
    "industry": "finance"
  }'
```

| Field        | Type   | Required | Description                             |
| :----------- | :----- | :------- | :-------------------------------------- |
| `email`      | string | yes      | Contact email address                   |
| `first_name` | string | yes      | Contact first name                      |
| `last_name`  | string | yes      | Contact last name                       |
| `company`    | string | no       | Organization name                       |
| `title`      | string | no       | Job title                               |
| `industry`   | string | no       | Industry (e.g. `finance`, `healthcare`) |

On success the endpoint returns HTTP 201 with the new lead object. See the [API reference](/api-reference/leads/create) for full request and response details.

### List leads

Retrieve all leads. Requires platform administrator authentication.

```bash theme={null}
curl -X GET https://api.truthlocks.com/v1/platform/leads \
  -H "Authorization: Bearer <admin_token>"
```

Each lead in the response includes:

| Field        | Type           | Description                                        |
| :----------- | :------------- | :------------------------------------------------- |
| `id`         | string         | Unique lead identifier                             |
| `first_name` | string         | Contact first name                                 |
| `last_name`  | string         | Contact last name                                  |
| `email`      | string         | Contact email address                              |
| `company`    | string or null | Organization name                                  |
| `message`    | string         | The original inquiry message                       |
| `source`     | string         | Lead source (e.g. `website`, `referral`)           |
| `status`     | string         | One of `new`, `contacted`, `qualified`, `archived` |
| `created_at` | string         | ISO 8601 timestamp                                 |
| `updated_at` | string         | ISO 8601 timestamp                                 |

### Get a lead

```bash theme={null}
curl -X GET https://api.truthlocks.com/v1/platform/leads/{id} \
  -H "Authorization: Bearer <admin_token>"
```

### Update lead status

```bash theme={null}
curl -X PATCH https://api.truthlocks.com/v1/platform/leads/{id}/status \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{"status": "contacted"}'
```

Pass any valid status: `new`, `contacted`, `qualified`, or `archived`.

### Convert a lead

Send an enterprise onboarding invite to the lead's email and begin the tenant creation process:

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/platform/leads/{id}/convert \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

On success, the response includes a confirmation message and the lead's status is set to `qualified`.

## Related

<CardGroup cols={2}>
  <Card title="AI CMO" icon="robot" href="/guides/ai-cmo">
    Automated outbound campaigns with AI-driven lead discovery and scoring.
  </Card>

  <Card title="Console onboarding" icon="rocket" href="/guides/console-onboarding">
    The guided wizard new tenants follow after receiving an onboarding invite.
  </Card>

  <Card title="B2G procurement" icon="building-columns" href="/packs/enterprise/b2g-procurement">
    Enterprise onboarding flow for government tenants.
  </Card>

  <Card title="Email delivery" icon="envelope" href="/security/email-delivery">
    Email templates and delivery infrastructure, including enterprise onboarding invites.
  </Card>
</CardGroup>