---
title: "Upsert leads."
method: POST
path: "/api/external/v1/leads/upsert-leads"
tags: ["Leads"]
---

# Upsert leads.

`POST /api/external/v1/leads/upsert-leads`

This endpoint is used to upsert (update or insert) leads.

The leads are sent in the request body.
The leads are an array of objects.
The leads.*.values are key/value pairs with the values of the lead.

---
### Required fields for creating or updating a lead

**To create a new lead, at least one of:**
- `email`
- `linkedin_profile_url`

**To update an existing lead, at least one of:**
- `lead_id` (GenPage Lead ID)
- `genpage_url` (GenPage URL)

---
### Optional but strongly recommended fields
- `first_name`
- `company_name`
- `company_domain`
---

The response is the job ID.

The job ID can be used to get the status of the job, and get all the leads that were upserted by this request.

## Request body

- object
  - `from` string, nullable — The service that is sending the leads, use your own company/service name please. Defaults to NOT_SPECIFIED.
  - `campaign_id` integer, required — The campaign ID to add the leads to.
  - `audience_id` integer, nullable — The audience ID to add the leads to.
  - `callback_url` string, nullable — Optional callback URL.
  - `send_email` boolean, nullable — Send the configured email for each upserted lead. Defaults to false.
  - `is_generate_ai_analysis` boolean, nullable — Whether to generate AI analysis for the leads.
  - `enrich_data` boolean, nullable — Enrich the leads from their email/domain.
  - `generate_ai_variables` boolean, nullable — Generate AI variable values for the leads. Defaults to false.
  - `leads` object[], required — Array of lead objects to upsert.
    - `lead_id` integer, nullable — The GenPage Lead ID for updating existing leads.
    - `genpage_url` string, nullable — The GenPage URL for updating existing leads.
    - `values` object, nullable, required — Object containing key/value pairs with the lead data. You can send any key/value (value can be a string or a number) pairs that you want to add to the lead.
      - `first_name` string — The first name of the lead.
      - `last_name` string — The last name of the lead.
      - `email` string — The email address of the lead.
      - `company_name` string — The company name of the lead.
      - `linkedin_profile_url` string — The LinkedIn profile URL of the lead.
      - `company_domain` string — The company domain of the lead.
      - `my_custom_variable` string — Custom variable for the lead.

## Response `200`

- object
  - `job_id` string

## Other responses

- `401`

## Changes

- **2026-08-18** `29a37db12acb` — 2 breaking, 4 info
  - added the new required request property `leads/items/values`
  - the `leads/items/` request property type/format changed from `string`/`` to `object`/``
  - added the new optional request property `leads/items/genpage_url`
  - added the new optional request property `leads/items/lead_id`
  - …2 more
- **2026-08-17** `dd3f47f72f7a` — 3 info
  - added the new optional request property `enrich_data`
  - added the new optional request property `generate_ai_variables`
  - added the new optional request property `send_email`

[Change history](https://skmtc.dev/genpage/apis/genpage-external-api-documentation/changes/api/external/v1/leads/upsert-leads/post.md)

---

[API](https://skmtc.dev/genpage/apis/genpage-external-api-documentation.md) · [All operations](https://skmtc.dev/genpage/apis/genpage-external-api-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/genpage/genpage-external-api-documentation/revisions/29a37db12acb/schema)