# Create a lead (/api-reference/leads/createLead)

## POST /api/v1/leads/

Operation ID: `createLead`
Create a lead
Creates one lead and optionally adds it to campaigns. The phone is stored in E.164 form (a 10-digit number gets `+91`, as in a CSV upload); a number that cannot be read is refused with `invalid_phone_number`. The number is not checked for duplicates. Values that could not be saved as sent (an unknown status, a mistyped field) come back in `warnings`.

### Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `Idempotency-Key` | header | no | Any unique string up to 255 characters. Retrying with the same key and body within 24 hours returns the first result instead of acting twice. |

### Request body

`application/json` (required)

```json
{
  "description": "A new lead. Every field is optional; send at least a phone number to call it.",
  "properties": {
    "attributes": {
      "additionalProperties": true,
      "description": "Profile facts, for example `{\"city\": \"Pune\"}`. Typed by your lead fields.",
      "title": "Attributes",
      "type": "object"
    },
    "campaignIds": {
      "description": "Add the lead to these campaigns.",
      "items": {
        "type": "string"
      },
      "title": "Campaignids",
      "type": "array"
    },
    "company": {
      "default": "",
      "description": "Company name.",
      "title": "Company",
      "type": "string"
    },
    "email": {
      "default": "",
      "description": "Email address.",
      "title": "Email",
      "type": "string"
    },
    "leadSourceId": {
      "default": "",
      "description": "ID of an existing lead source.",
      "title": "Leadsourceid",
      "type": "string"
    },
    "name": {
      "default": "",
      "description": "Full name.",
      "title": "Name",
      "type": "string"
    },
    "notes": {
      "default": "",
      "description": "Saved as the lead's first note.",
      "title": "Notes",
      "type": "string"
    },
    "phone": {
      "default": "",
      "description": "Phone number, saved in E.164 form: `+919876543210`, `9876543210` and `098765 43210` all save as `+919876543210` (a number without a country code is taken as Indian). A value that is not a phone number returns 422 `invalid_phone_number`.",
      "title": "Phone",
      "type": "string"
    },
    "source": {
      "default": "",
      "description": "Free-text source label, for example `website`.",
      "title": "Source",
      "type": "string"
    },
    "status": {
      "default": "new",
      "description": "Pipeline status key. An unknown key saves as `new` with a warning.",
      "title": "Status",
      "type": "string"
    },
    "title": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": "",
      "description": "Job title.",
      "title": "Title"
    }
  },
  "title": "LeadCreate",
  "type": "object"
}
```

Example:

```json
{
  "attributes": {
    "city": "Pune"
  },
  "company": "Rao Traders",
  "email": "asha@example.com",
  "name": "Asha Rao",
  "phone": "9876543210"
}
```

### Responses

#### 200 OK

Example (example):

```json
{
  "lead": {
    "attributes": {
      "city": "Pune"
    },
    "callAttempts": 0,
    "callStatus": "not_called",
    "campaignIds": [],
    "campaignNames": [],
    "company": "Rao Traders",
    "createdAt": "2026-11-15T10:00:00+00:00",
    "dncOptOut": false,
    "email": "asha@example.com",
    "id": "6f1c2a9e-3b7d-4c55-9a0e-1d2f3a4b5c6d",
    "name": "Asha Rao",
    "phone": "+919876543210",
    "source": "website",
    "status": "new",
    "tags": [],
    "title": "Owner",
    "updatedAt": "2026-11-15T10:00:00+00:00"
  },
  "success": true,
  "warnings": []
}
```

#### 400 Bad request: `bad_request`.

Example (The request could not be processed.):

```json
{
  "detail": "The request could not be processed.",
  "error": {
    "code": "bad_request",
    "docUrl": "https://docs.callmitra.ai/errors/bad_request",
    "message": "The request could not be processed.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "invalid_request_error"
  }
}
```

#### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`.

Example (The API key has expired.):

```json
{
  "detail": "The API key has expired.",
  "error": {
    "code": "api_key_expired",
    "docUrl": "https://docs.callmitra.ai/errors/api_key_expired",
    "message": "The API key has expired.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "authentication_error"
  }
}
```

Example (The API key is invalid or has been revoked.):

```json
{
  "detail": "The API key is invalid or has been revoked.",
  "error": {
    "code": "invalid_api_key",
    "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key",
    "message": "The API key is invalid or has been revoked.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "authentication_error"
  }
}
```

Example (Authentication required.):

```json
{
  "detail": "Authentication required.",
  "error": {
    "code": "unauthenticated",
    "docUrl": "https://docs.callmitra.ai/errors/unauthenticated",
    "message": "Authentication required.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "authentication_error"
  }
}
```

#### 403 Forbidden: `api_key_scope_denied`, `permission_denied`.

Example (The API key does not have the scope required for this request.):

```json
{
  "detail": "The API key does not have the scope required for this request.",
  "error": {
    "code": "api_key_scope_denied",
    "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied",
    "message": "The API key does not have the scope required for this request.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "permission_error"
  }
}
```

Example (You do not have permission to perform this action.):

```json
{
  "detail": "You do not have permission to perform this action.",
  "error": {
    "code": "permission_denied",
    "docUrl": "https://docs.callmitra.ai/errors/permission_denied",
    "message": "You do not have permission to perform this action.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "permission_error"
  }
}
```

#### 404 Not found: `campaign_not_found`.

Example (Campaign not found.):

```json
{
  "detail": "Campaign not found.",
  "error": {
    "code": "campaign_not_found",
    "docUrl": "https://docs.callmitra.ai/errors/campaign_not_found",
    "message": "Campaign not found.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "not_found_error"
  }
}
```

#### 409 Conflict: `idempotency_key_reused`, `idempotency_request_in_progress`.

Example (This Idempotency-Key was already used with a different request body.):

```json
{
  "detail": "This Idempotency-Key was already used with a different request body.",
  "error": {
    "code": "idempotency_key_reused",
    "docUrl": "https://docs.callmitra.ai/errors/idempotency_key_reused",
    "message": "This Idempotency-Key was already used with a different request body.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "idempotency_error"
  }
}
```

Example (A request with this Idempotency-Key is still being processed.):

```json
{
  "detail": "A request with this Idempotency-Key is still being processed.",
  "error": {
    "code": "idempotency_request_in_progress",
    "docUrl": "https://docs.callmitra.ai/errors/idempotency_request_in_progress",
    "message": "A request with this Idempotency-Key is still being processed.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "idempotency_error"
  }
}
```

#### 422 Invalid parameters: `invalid_phone_number`, `parameter_invalid`.

Example (The phone number is not valid.):

```json
{
  "detail": [
    {
      "loc": [
        "body",
        "phone"
      ],
      "msg": "Field required",
      "type": "missing"
    }
  ],
  "error": {
    "code": "invalid_phone_number",
    "docUrl": "https://docs.callmitra.ai/errors/invalid_phone_number",
    "message": "The phone number is not valid.",
    "param": "phone",
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "invalid_request_error"
  }
}
```

Example (One or more parameters are invalid.):

```json
{
  "detail": [
    {
      "loc": [
        "body",
        "phone"
      ],
      "msg": "Field required",
      "type": "missing"
    }
  ],
  "error": {
    "code": "parameter_invalid",
    "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid",
    "message": "One or more parameters are invalid.",
    "param": "phone",
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "invalid_request_error"
  }
}
```

#### 429 Too many requests: `rate_limit_exceeded`.

Example (Too many requests. Slow down and retry later.):

```json
{
  "detail": "Too many requests. Slow down and retry later.",
  "error": {
    "code": "rate_limit_exceeded",
    "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded",
    "message": "Too many requests. Slow down and retry later.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "rate_limit_error"
  }
}
```

#### 500 Server error: `internal_error`.

Example (Something went wrong on our side.):

```json
{
  "detail": "Something went wrong on our side.",
  "error": {
    "code": "internal_error",
    "docUrl": "https://docs.callmitra.ai/errors/internal_error",
    "message": "Something went wrong on our side.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "api_error"
  }
}
```

### Error codes

- [`bad_request`](/errors/bad_request)
- [`api_key_expired`](/errors/api_key_expired)
- [`invalid_api_key`](/errors/invalid_api_key)
- [`unauthenticated`](/errors/unauthenticated)
- [`api_key_scope_denied`](/errors/api_key_scope_denied)
- [`permission_denied`](/errors/permission_denied)
- [`campaign_not_found`](/errors/campaign_not_found)
- [`idempotency_key_reused`](/errors/idempotency_key_reused)
- [`idempotency_request_in_progress`](/errors/idempotency_request_in_progress)
- [`invalid_phone_number`](/errors/invalid_phone_number)
- [`parameter_invalid`](/errors/parameter_invalid)
- [`rate_limit_exceeded`](/errors/rate_limit_exceeded)
- [`internal_error`](/errors/internal_error)
