---
title: "Create a lead"
method: POST
path: "/api/v1/rest/crm/leads"
tags: ["CRM"]
---

# Create a lead

`POST /api/v1/rest/crm/leads`

## Request

- Base URL: `https://api.custodo.ai`
- URL: `https://api.custodo.ai/api/v1/rest/crm/leads`
- Auth: HTTP bearer

Files an unqualified enquiry in the lead inbox — a name, a company and a way to reach them, before anybody has decided it is a real opportunity. The contact details are kept as they arrived and are copied forward, never synced back, when the lead is converted. The lead inbox is OFF for most organisations: if it is off here this tool says so and the answer is an ordinary deal instead. It becomes yours and appears in the CRM immediately, so confirm the details with the user first.

## Headers

- `X-Tenant-Id` string, uuid

## Request body

- object
  - `title` string, required: What the enquiry is about, as it should read in the list.
  - `contact_name` string: The person who got in touch.
  - `company` string: Their organisation, as they gave it. Not matched against the anagrafica.
  - `email` string
  - `phone` string
  - `source` string: Where it came from — «sito», «passaparola», «fiera». Free text.
  - `amount` number: Expected value in the tenant’s currency. Omit when nobody has said.
  - `expected_close_date` string: When it might close, YYYY-MM-DD. Optional on a lead; required once it becomes a deal.

## Response `200`

Done. `data` is the tool’s own answer.

- RestResult
  - `ok` true, required
  - `data` unknown, required

## Other responses

- `400`: The arguments did not validate: `error.message` names the field, what it expects and what arrived.
- `401`: No API key, or one that is malformed, unknown, revoked or expired.
- `403`: The call never ran: the module is off for this organisation, the credential lacks the permission or the module, the tier does not cover it, or the tool is destructive and the key was not minted for that.
- `409`: The record is in a state that does not allow it — under legal hold, already sent, already closed. `error.code` says which.
- `422`: The tool ran and refused, in a sentence of its own (`TOOL_REFUSED`): the message says what to change. Retrying the same call will not help.
- `429`: The API key has spent its minute, or its day. Every request a key makes counts. See `Retry-After`.

---

[API](https://skmtc.dev/custodo/apis/custodo-integrazioni.md) · [All operations](https://skmtc.dev/custodo/apis/custodo-integrazioni/llms.txt) · [OpenAPI document](https://skmtc.dev/custodo/apis/custodo-integrazioni/revisions/16d336d3ec2a?raw)