---
title: "Create a new lead"
method: POST
path: "/api/business/{businessId}/branch/{branchId}/leads"
tags: ["Lead"]
---

# Create a new lead

`POST /api/business/{businessId}/branch/{branchId}/leads`

## Request

- Base URL: `http://api-gateway-eu.phorest.com/third-party-api-server`
- URL: `http://api-gateway-eu.phorest.com/third-party-api-server/api/business/{businessId}/branch/{branchId}/leads`
- Auth: HTTP basic
- TypeScript: <https://skmtc.dev/phorest/apis/third-party-api/docs/api/business/:businessId/branch/:branchId/leads/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a new lead. Either contactableByEmail or contactableByMobile need to be provided.

## Path parameters

- `businessId` string, required
- `branchId` string, required

## Request body

- LeadCreateRequest
  - `businessId` string, required: The business ID
  - `branchId` string, required: The branch ID
  - `firstName` string, required: First name of the lead
  - `lastName` string, required: Last name of the lead
  - `mobile` string, required: Mobile phone number
  - `email` string, required: Email address
  - `source` string: Source of the lead - defaults to THIRD_PARTY_API
  - `contactableByEmail` boolean: Whether the lead can be contacted by email
  - `contactableByMobile` boolean: Whether the lead can be contacted by mobile
  - `marketingOptIn` boolean: Whether the lead has opted in for marketing
  - `metaAdId` string: Meta ad ID
  - `note` string: Additional notes about the lead

## Response `201`

Lead created successfully

- LeadCreateResponse
  - `success` boolean: Whether the lead was successfully created
  - `message` string: Response message

## Other responses

- `400`: Lead data is invalid, unable to create a lead
- `404`: Business or branch with the specified ids don't exist
- `429`: Request rate limit exceeded. Current limit set to 100 rps.
- `500`: Internal Server Error

---

[API](https://skmtc.dev/phorest/apis/third-party-api.md) - [All operations](https://skmtc.dev/phorest/apis/third-party-api/llms.txt) - [OpenAPI document](https://skmtc.dev/phorest/apis/third-party-api/revisions/beea6ef29634?raw)