---
title: "Create a lead"
method: POST
path: "/v2/leads"
tags: ["Leads"]
---

# Create a lead

`POST /v2/leads`

Creates a lead with desired params.

## Request body

- union — Either 'stage_api_name' or 'status' must be provided (or both). If both are provided, 'stage_api_name' takes precedence. Use 'stage_api_name' for precise stage control with custom sales cycles, or 'status' for status management.
  - object
    - `amount` integer, nullable — Lead amount in **cents**
    - `approved` true | false, nullable — Used to indicate whether this lead has been approved to move past the closed stage
    - `external_key` string, required — A unique key that identifies this lead in an external system. This key must be unique across all leads in your account. This key is used to identify leads when they are updated or deleted. Often provided as an email, but can be any unique string.
    - `field_data` object, nullable
    - `fields` object[]
      - `api_name` string — API name of this field to be used on create / update / serialization. Created at time of field creation but can be edited
      - `description` string, nullable — Description of the field to be displayed to the partner
      - `external_type` string, nullable — Name that can be used for external systems
      - `field_key` string — Key of field that is presented
      - `help_text` string, nullable — The help text that is provided for this field
      - `hidden` boolean — Whether or not this field is displayed when filling out its attached form
      - `internal_name` string — Internal name of this field. Created by PartnerStack at time of field creation. Used when referencing field in created objects. Cannot be edited.
      - `name` string — Name of field that is presented
      - `options` object — Options to select from if this field is a picklist/checkbox
      - `placeholder_text` string, nullable — The text of the placeholder that is provided for this field
      - `position` integer — The position that this field will be displayed in relation to others on the same form (index starts at 0)
      - `read_only` boolean — Whether or not this field is read only
      - `required` boolean — Whether or not this field will be required when filling out its attached form
      - `type` string — The type of field that will be presented (input, picklist, number ect.)
      - `value` unknown
    - `group_key` string, nullable
    - `meta` object, required — Key value pairs that store additional information about this lead. First and last name required. Other eligible keys are based on Lead forms created. Use the /leads/form-template to view field names
      - `company` string, required
      - `email` string
      - `first_name` string, required
      - `last_name` string, required
    - `mold_key` string, nullable
    - `partner_key` string, required — The unique key of the partner who submitted this lead
    - `personal_stack_key` string, nullable — The unique personal stack_key of the partner team member who submitted this lead. To select a team member, please pass either the personal_stack_key or the team_member_email.
    - `stage_api_name` string, required — The api_name of the Stage this lead should be in. This is used to determine the current stage of the lead. If not provided, the lead will be placed in the first stage of the sales cycle.
    - `status` 'open' | 'closed' | 'dead' | 'closed won' | 'closed lost' — Current status of this lead. Must be one of either 'open', 'closed', 'dead', 'closed won', or 'closed lost'. Note that open = New, closed = Qualified and dead = Unqualified default stages in the PartnerStack dashboard.
    - `team_member_email` string, nullable — The email of the partner team member who submitted this lead. To select a team member, please pass either the personal_stack_key or the team_member_email.
  - object
    - `amount` integer, nullable — Lead amount in **cents**
    - `approved` true | false, nullable — Used to indicate whether this lead has been approved to move past the closed stage
    - `external_key` string, required — A unique key that identifies this lead in an external system. This key must be unique across all leads in your account. This key is used to identify leads when they are updated or deleted. Often provided as an email, but can be any unique string.
    - `field_data` object, nullable
    - `fields` object[]
      - `api_name` string — API name of this field to be used on create / update / serialization. Created at time of field creation but can be edited
      - `description` string, nullable — Description of the field to be displayed to the partner
      - `external_type` string, nullable — Name that can be used for external systems
      - `field_key` string — Key of field that is presented
      - `help_text` string, nullable — The help text that is provided for this field
      - `hidden` boolean — Whether or not this field is displayed when filling out its attached form
      - `internal_name` string — Internal name of this field. Created by PartnerStack at time of field creation. Used when referencing field in created objects. Cannot be edited.
      - `name` string — Name of field that is presented
      - `options` object — Options to select from if this field is a picklist/checkbox
      - `placeholder_text` string, nullable — The text of the placeholder that is provided for this field
      - `position` integer — The position that this field will be displayed in relation to others on the same form (index starts at 0)
      - `read_only` boolean — Whether or not this field is read only
      - `required` boolean — Whether or not this field will be required when filling out its attached form
      - `type` string — The type of field that will be presented (input, picklist, number ect.)
      - `value` unknown
    - `group_key` string, nullable
    - `meta` object, required — Key value pairs that store additional information about this lead. First and last name required. Other eligible keys are based on Lead forms created. Use the /leads/form-template to view field names
      - `company` string, required
      - `email` string
      - `first_name` string, required
      - `last_name` string, required
    - `mold_key` string, nullable
    - `partner_key` string, required — The unique key of the partner who submitted this lead
    - `personal_stack_key` string, nullable — The unique personal stack_key of the partner team member who submitted this lead. To select a team member, please pass either the personal_stack_key or the team_member_email.
    - `stage_api_name` string — The api_name of the Stage this lead should be in. This is used to determine the current stage of the lead. If not provided, the lead will be placed in the first stage of the sales cycle.
    - `status` 'open' | 'closed' | 'dead' | 'closed won' | 'closed lost', required — Current status of this lead. Must be one of either 'open', 'closed', 'dead', 'closed won', or 'closed lost'. Note that open = New, closed = Qualified and dead = Unqualified default stages in the PartnerStack dashboard.
    - `team_member_email` string, nullable — The email of the partner team member who submitted this lead. To select a team member, please pass either the personal_stack_key or the team_member_email.
  - object
    - `amount` integer, nullable — Lead amount in **cents**
    - `approved` true | false, nullable — Used to indicate whether this lead has been approved to move past the closed stage
    - `external_key` string, required — A unique key that identifies this lead in an external system. This key must be unique across all leads in your account. This key is used to identify leads when they are updated or deleted. Often provided as an email, but can be any unique string.
    - `field_data` object, nullable
    - `fields` object[]
      - `api_name` string — API name of this field to be used on create / update / serialization. Created at time of field creation but can be edited
      - `description` string, nullable — Description of the field to be displayed to the partner
      - `external_type` string, nullable — Name that can be used for external systems
      - `field_key` string — Key of field that is presented
      - `help_text` string, nullable — The help text that is provided for this field
      - `hidden` boolean — Whether or not this field is displayed when filling out its attached form
      - `internal_name` string — Internal name of this field. Created by PartnerStack at time of field creation. Used when referencing field in created objects. Cannot be edited.
      - `name` string — Name of field that is presented
      - `options` object — Options to select from if this field is a picklist/checkbox
      - `placeholder_text` string, nullable — The text of the placeholder that is provided for this field
      - `position` integer — The position that this field will be displayed in relation to others on the same form (index starts at 0)
      - `read_only` boolean — Whether or not this field is read only
      - `required` boolean — Whether or not this field will be required when filling out its attached form
      - `type` string — The type of field that will be presented (input, picklist, number ect.)
      - `value` unknown
    - `group_key` string, nullable
    - `meta` object, required — Key value pairs that store additional information about this lead. First and last name required. Other eligible keys are based on Lead forms created. Use the /leads/form-template to view field names
      - `company` string, required
      - `email` string
      - `first_name` string, required
      - `last_name` string, required
    - `mold_key` string, nullable
    - `partner_key` string, required — The unique key of the partner who submitted this lead
    - `personal_stack_key` string, nullable — The unique personal stack_key of the partner team member who submitted this lead. To select a team member, please pass either the personal_stack_key or the team_member_email.
    - `stage_api_name` string, required — The api_name of the Stage this lead should be in. This is used to determine the current stage of the lead. If not provided, the lead will be placed in the first stage of the sales cycle.
    - `status` 'open' | 'closed' | 'dead' | 'closed won' | 'closed lost', required — Current status of this lead. Must be one of either 'open', 'closed', 'dead', 'closed won', or 'closed lost'. Note that open = New, closed = Qualified and dead = Unqualified default stages in the PartnerStack dashboard.
    - `team_member_email` string, nullable — The email of the partner team member who submitted this lead. To select a team member, please pass either the personal_stack_key or the team_member_email.

## Response `200`

Creates a lead with desired params.

- object
  - `data` object, required — **Leads** are submitted by your partners to let your sales team know of potential accounts that they may wish to work. Partners may earn comission for qualified leads, or leads that eventually become closed accounts.
    - `created_at` integer — Immutable Unix timestamp in milliseconds taken at time of creation
    - `key` string — A unique identifier used to reference the object
    - `updated_at` integer — Unix timestamp in milliseconds taken at time of last update
    - `amount` integer, nullable — Lead amount in **cents**
    - `approved` boolean, nullable — Used to indicate whether this lead has been approved to move past the closed stage
    - `customer_key` string, nullable — Unique identifier to be used for Customer after a lead has been converted
    - `external_key` string — A unique key that identifies this lead in an external system. This key must be unique across all leads in your account. This key is used to identify leads when they are updated or deleted. Often provided as an email, but can be any unique string.
    - `field_data` object, nullable
    - `fields` object[]
      - `api_name` string — API name of this field to be used on create / update / serialization. Created at time of field creation but can be edited
      - `description` string, nullable — Description of the field to be displayed to the partner
      - `external_type` string, nullable — Name that can be used for external systems
      - `field_key` string — Key of field that is presented
      - `help_text` string, nullable — The help text that is provided for this field
      - `hidden` boolean — Whether or not this field is displayed when filling out its attached form
      - `internal_name` string — Internal name of this field. Created by PartnerStack at time of field creation. Used when referencing field in created objects. Cannot be edited.
      - `name` string — Name of field that is presented
      - `options` object — Options to select from if this field is a picklist/checkbox
      - `placeholder_text` string, nullable — The text of the placeholder that is provided for this field
      - `position` integer — The position that this field will be displayed in relation to others on the same form (index starts at 0)
      - `read_only` boolean — Whether or not this field is read only
      - `required` boolean — Whether or not this field will be required when filling out its attached form
      - `type` string — The type of field that will be presented (input, picklist, number ect.)
      - `value` unknown
    - `group_key` string, nullable
    - `meta` object, nullable — Key value pairs that store additional information about this lead. First and last name required. Other eligible keys are based on Lead forms created. Use the /leads/form-template to view field names
      - `company` string
      - `email` string
      - `first_name` string
      - `last_name` string
    - `mold_key` string, nullable
    - `partner_key` string — The unique key of the partner who submitted this lead
    - `stage_data` object, nullable — Information about the current lead's stage
      - `api_name` string, nullable — A unique identifier that reflects what this stage means in a vendor's external system, like a CRM.
      - `description` string, nullable — A description of this stage in the sales pipeline
      - `internal_status` string, nullable — What the given stage represents internally to PartnerStack
      - `key` string, nullable — A unique key that references the stage within PartnerStack's systems
      - `name` string, nullable — The name of the stage
    - `status` 'open' | 'closed' | 'dead' | 'closed won' | 'closed lost' — Current status of this lead. Must be one of either 'open', 'closed', 'dead', 'closed won', or 'closed lost. Note that open = New, closed = Qualified and dead = Unqualified default stages in the PartnerStack dashboard.'
    - `team` object, nullable — Details of team used in public API.
      - `created_at` integer — Immutable Unix timestamp in milliseconds taken at time of creation
      - `key` string — A unique identifier used to reference the object
      - `updated_at` integer — Unix timestamp in milliseconds taken at time of last update
      - `name` string — The name of the partner team
    - `team_member` object, nullable — Details of team member used in public API.
      - `created_at` integer — Immutable Unix timestamp in milliseconds taken at time of creation
      - `key` string — A unique identifier used to reference the object
      - `updated_at` integer — Unix timestamp in milliseconds taken at time of last update
      - `email` string — Email of the partner team member
      - `first_name` string — First name of the partner team member
      - `last_name` string — Last name of the partner team member
      - `personal_stack_key` string — The personal stack key of the partner team member
  - `message` string, required
  - `status` integer, required

## Other responses

- `400` — Bad Request Error
- `401` — Unauthorized Error
- `403` — Forbidden Error
- `404` — Not Found Error
- `500` — Internal Server Error

---

[API](https://skmtc.dev/partnerstack/apis/partnerstack-api.md) · [All operations](https://skmtc.dev/partnerstack/apis/partnerstack-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/partnerstack/partnerstack-api/revisions/0f35aebe53a9/schema)