---
title: "Upsert Lead"
method: POST
path: "/leads"
tags: ["Leads"]
---

# Upsert Lead

`POST /leads`

Creates a new lead or updates the existing lead in the organization with that phone number.

## Request body

- object
  - `phoneNumber` string, required — The phone number of the lead. The combination of organizationId and phoneNumber represent a lead. Attempting to insert a new lead with these existing values will overwrite the existing lead.
  - `organizationId` string, required — The ID of the organization the lead belongs to. The combination of organizationId and phoneNumber represent a lead. Attempting to insert a new lead with these existing values will overwrite the existing lead.
  - `activeGroupIds` string[] — The IDs of the groups to make the lead active in. The lead will also be added to the group if they are not already. Excluding a group from this array will not make a lead inactive in that group. Use inactiveGroupIds to perform that operation. All groups must belong to the same organization as the lead.
  - `inactiveGroupIds` string[] — The IDs of the groups to make the lead inactive in. All groups must belong to the same organization as the lead and the lead must already belong to them. If a lead is not already part of a passed group, they will *not* be added and deactivated (This property is only useful during lead updates and not inserts and exists only due to the limitation where leads CANNOT be removed from groups).
  - `customFields` object — The custom fields and associated values for the lead.
  - `firstName` string — The first name of the lead.
  - `lastName` string — The last name of the lead.
  - `notes` string — Notes about the lead.
  - `followUp` string — Follow up comments for the lead.
  - `email` string — The email of the lead.
  - `postalCode` string — The postal (AKA zip) code of the lead.
  - `phoneNumberType` 'mobile' | 'landline' | 'voip' | 'invalid' | 'blacklisted' — The type of phone number of the lead. Older leads or leads that have not been messaged recently may not have this data available.
  - `tagIds` string[] — The IDs of the tags that have been applied to the lead.

## Response `200`

Returns an updated lead and denotes the operation was an update.

- Lead — A lead represents someone that messages and calls are sent to.
  - `id` string, required — The ID of the lead.
  - `type` 'lead', required — The type of object the attached ID corresponds to.
  - `phoneNumber` string, required — The phone number of the lead. The combination of organizationId and phoneNumber represent a lead. Attempting to insert a new lead with these existing values will overwrite the existing lead.
  - `organizationId` string, required — The ID of the organization the lead belongs to. The combination of organizationId and phoneNumber represent a lead. Attempting to insert a new lead with these existing values will overwrite the existing lead.
  - `activeGroupIds` string[], required — The IDs of the groups the lead belongs to where they are still active.
  - `inactiveGroupIds` string[], required — The IDs of the groups the lead belongs to where the lead is inactive. Because deleting a lead from a group is not allowed, the only way to stop a lead from receiving messages meant for a group is to make them inactive.
  - `customFields` object, required — The custom fields and associated values for the lead.
  - `firstName` string — The first name of the lead.
  - `lastName` string — The last name of the lead.
  - `notes` string — Notes about the lead.
  - `followUp` string — Follow up comments for the lead.
  - `email` string — The email of the lead.
  - `postalCode` string — The postal (AKA zip) code of the lead.
  - `phoneNumberType` 'mobile' | 'landline' | 'voip' | 'invalid' | 'blacklisted' — The type of phone number of the lead. Older leads or leads that have not been messaged recently may not have this data available.
  - `tagIds` string[], required — The IDs of the tags that have been applied to the lead.
  - `globalOptedOut` boolean, required — Whether or not the lead has opted out of all messages. If this is true, the lead will not receive any messages.
  - `createdAt` string, required — An ISO-8601 string representing the date the agent was created.

## Other responses

- `201` — Returns the created lead and denotes the operation was a creation.
- `400` — Bad Request
- `401` — Unauthorized
- `404` — Not Found
- `422` — Unprocessable Entity
- `500` — Internal Server Error

---

[API](https://skmtc.net/hustle/apis/hustle-public-api.md) · [All operations](https://skmtc.net/hustle/apis/hustle-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/hustle/hustle-public-api/revisions/e920ac8ed225/schema)