Add or update a lead
curl --request POST \
--url https://prod.leadvector.app/v1/leads/{uuid} \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"email": "john.doe@example.com",
"leadId": 42,
"firstName": "John",
"lastName": "Doe",
"companyName": "Acme Inc.",
"pauseUntil": "2026-06-30T00:00:00.000Z",
"variables": [
{
"name": "jobTitle",
"value": "Software Engineer"
},
{
"name": "country",
"value": "Pakistan"
}
]
}
'import requests
url = "https://prod.leadvector.app/v1/leads/{uuid}"
payload = {
"email": "john.doe@example.com",
"leadId": 42,
"firstName": "John",
"lastName": "Doe",
"companyName": "Acme Inc.",
"pauseUntil": "2026-06-30T00:00:00.000Z",
"variables": [
{
"name": "jobTitle",
"value": "Software Engineer"
},
{
"name": "country",
"value": "Pakistan"
}
]
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
email: 'john.doe@example.com',
leadId: 42,
firstName: 'John',
lastName: 'Doe',
companyName: 'Acme Inc.',
pauseUntil: '2026-06-30T00:00:00.000Z',
variables: [
{name: 'jobTitle', value: 'Software Engineer'},
{name: 'country', value: 'Pakistan'}
]
})
};
fetch('https://prod.leadvector.app/v1/leads/{uuid}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://prod.leadvector.app/v1/leads/{uuid}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'email' => 'john.doe@example.com',
'leadId' => 42,
'firstName' => 'John',
'lastName' => 'Doe',
'companyName' => 'Acme Inc.',
'pauseUntil' => '2026-06-30T00:00:00.000Z',
'variables' => [
[
'name' => 'jobTitle',
'value' => 'Software Engineer'
],
[
'name' => 'country',
'value' => 'Pakistan'
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://prod.leadvector.app/v1/leads/{uuid}"
payload := strings.NewReader("{\n \"email\": \"john.doe@example.com\",\n \"leadId\": 42,\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"companyName\": \"Acme Inc.\",\n \"pauseUntil\": \"2026-06-30T00:00:00.000Z\",\n \"variables\": [\n {\n \"name\": \"jobTitle\",\n \"value\": \"Software Engineer\"\n },\n {\n \"name\": \"country\",\n \"value\": \"Pakistan\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://prod.leadvector.app/v1/leads/{uuid}")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"email\": \"john.doe@example.com\",\n \"leadId\": 42,\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"companyName\": \"Acme Inc.\",\n \"pauseUntil\": \"2026-06-30T00:00:00.000Z\",\n \"variables\": [\n {\n \"name\": \"jobTitle\",\n \"value\": \"Software Engineer\"\n },\n {\n \"name\": \"country\",\n \"value\": \"Pakistan\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://prod.leadvector.app/v1/leads/{uuid}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"email\": \"john.doe@example.com\",\n \"leadId\": 42,\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"companyName\": \"Acme Inc.\",\n \"pauseUntil\": \"2026-06-30T00:00:00.000Z\",\n \"variables\": [\n {\n \"name\": \"jobTitle\",\n \"value\": \"Software Engineer\"\n },\n {\n \"name\": \"country\",\n \"value\": \"Pakistan\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"message": "Lead created successfully",
"data": {
"id": 42,
"leadStatus": "PENDING",
"currentStep": 1,
"nextScheduledAt": "2023-11-07T05:31:56Z",
"customFields": {
"jobTitle": "Head of Sales"
},
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}
}{
"statusCode": 401,
"message": "INVALID_API_KEY",
"traceId": "4f1c2b7e9a0d4c3b8e6f5a2d1c0b9e8f",
"timestamp": "2026-11-03T09:41:12.000Z",
"path": "/v1/find-email",
"error": "Unauthorized"
}{
"statusCode": 401,
"message": "INVALID_API_KEY",
"traceId": "4f1c2b7e9a0d4c3b8e6f5a2d1c0b9e8f",
"timestamp": "2026-11-03T09:41:12.000Z",
"path": "/v1/find-email",
"error": "Unauthorized"
}{
"statusCode": 401,
"message": "INVALID_API_KEY",
"traceId": "4f1c2b7e9a0d4c3b8e6f5a2d1c0b9e8f",
"timestamp": "2026-11-03T09:41:12.000Z",
"path": "/v1/find-email",
"error": "Unauthorized"
}{
"statusCode": 401,
"message": "INVALID_API_KEY",
"traceId": "4f1c2b7e9a0d4c3b8e6f5a2d1c0b9e8f",
"timestamp": "2026-11-03T09:41:12.000Z",
"path": "/v1/find-email",
"error": "Unauthorized"
}{
"statusCode": 401,
"message": "INVALID_API_KEY",
"traceId": "4f1c2b7e9a0d4c3b8e6f5a2d1c0b9e8f",
"timestamp": "2026-11-03T09:41:12.000Z",
"path": "/v1/find-email",
"error": "Unauthorized"
}{
"statusCode": 401,
"message": "RATE_LIMIT_EXCEEDED",
"traceId": "4f1c2b7e9a0d4c3b8e6f5a2d1c0b9e8f",
"timestamp": "2026-11-03T09:41:12.000Z",
"path": "/v1/find-email",
"limit": 10,
"windowSeconds": 60,
"retryAfterSeconds": 6,
"error": "Unauthorized"
}Leads
Add or update a lead
Adds one lead to the campaign, or updates one: the lead named by leadId, else the lead with this email. Variables are set by name.
POST
/
v1
/
leads
/
{uuid}
Add or update a lead
curl --request POST \
--url https://prod.leadvector.app/v1/leads/{uuid} \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"email": "john.doe@example.com",
"leadId": 42,
"firstName": "John",
"lastName": "Doe",
"companyName": "Acme Inc.",
"pauseUntil": "2026-06-30T00:00:00.000Z",
"variables": [
{
"name": "jobTitle",
"value": "Software Engineer"
},
{
"name": "country",
"value": "Pakistan"
}
]
}
'import requests
url = "https://prod.leadvector.app/v1/leads/{uuid}"
payload = {
"email": "john.doe@example.com",
"leadId": 42,
"firstName": "John",
"lastName": "Doe",
"companyName": "Acme Inc.",
"pauseUntil": "2026-06-30T00:00:00.000Z",
"variables": [
{
"name": "jobTitle",
"value": "Software Engineer"
},
{
"name": "country",
"value": "Pakistan"
}
]
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
email: 'john.doe@example.com',
leadId: 42,
firstName: 'John',
lastName: 'Doe',
companyName: 'Acme Inc.',
pauseUntil: '2026-06-30T00:00:00.000Z',
variables: [
{name: 'jobTitle', value: 'Software Engineer'},
{name: 'country', value: 'Pakistan'}
]
})
};
fetch('https://prod.leadvector.app/v1/leads/{uuid}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://prod.leadvector.app/v1/leads/{uuid}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'email' => 'john.doe@example.com',
'leadId' => 42,
'firstName' => 'John',
'lastName' => 'Doe',
'companyName' => 'Acme Inc.',
'pauseUntil' => '2026-06-30T00:00:00.000Z',
'variables' => [
[
'name' => 'jobTitle',
'value' => 'Software Engineer'
],
[
'name' => 'country',
'value' => 'Pakistan'
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://prod.leadvector.app/v1/leads/{uuid}"
payload := strings.NewReader("{\n \"email\": \"john.doe@example.com\",\n \"leadId\": 42,\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"companyName\": \"Acme Inc.\",\n \"pauseUntil\": \"2026-06-30T00:00:00.000Z\",\n \"variables\": [\n {\n \"name\": \"jobTitle\",\n \"value\": \"Software Engineer\"\n },\n {\n \"name\": \"country\",\n \"value\": \"Pakistan\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://prod.leadvector.app/v1/leads/{uuid}")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"email\": \"john.doe@example.com\",\n \"leadId\": 42,\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"companyName\": \"Acme Inc.\",\n \"pauseUntil\": \"2026-06-30T00:00:00.000Z\",\n \"variables\": [\n {\n \"name\": \"jobTitle\",\n \"value\": \"Software Engineer\"\n },\n {\n \"name\": \"country\",\n \"value\": \"Pakistan\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://prod.leadvector.app/v1/leads/{uuid}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"email\": \"john.doe@example.com\",\n \"leadId\": 42,\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"companyName\": \"Acme Inc.\",\n \"pauseUntil\": \"2026-06-30T00:00:00.000Z\",\n \"variables\": [\n {\n \"name\": \"jobTitle\",\n \"value\": \"Software Engineer\"\n },\n {\n \"name\": \"country\",\n \"value\": \"Pakistan\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"message": "Lead created successfully",
"data": {
"id": 42,
"leadStatus": "PENDING",
"currentStep": 1,
"nextScheduledAt": "2023-11-07T05:31:56Z",
"customFields": {
"jobTitle": "Head of Sales"
},
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}
}{
"statusCode": 401,
"message": "INVALID_API_KEY",
"traceId": "4f1c2b7e9a0d4c3b8e6f5a2d1c0b9e8f",
"timestamp": "2026-11-03T09:41:12.000Z",
"path": "/v1/find-email",
"error": "Unauthorized"
}{
"statusCode": 401,
"message": "INVALID_API_KEY",
"traceId": "4f1c2b7e9a0d4c3b8e6f5a2d1c0b9e8f",
"timestamp": "2026-11-03T09:41:12.000Z",
"path": "/v1/find-email",
"error": "Unauthorized"
}{
"statusCode": 401,
"message": "INVALID_API_KEY",
"traceId": "4f1c2b7e9a0d4c3b8e6f5a2d1c0b9e8f",
"timestamp": "2026-11-03T09:41:12.000Z",
"path": "/v1/find-email",
"error": "Unauthorized"
}{
"statusCode": 401,
"message": "INVALID_API_KEY",
"traceId": "4f1c2b7e9a0d4c3b8e6f5a2d1c0b9e8f",
"timestamp": "2026-11-03T09:41:12.000Z",
"path": "/v1/find-email",
"error": "Unauthorized"
}{
"statusCode": 401,
"message": "INVALID_API_KEY",
"traceId": "4f1c2b7e9a0d4c3b8e6f5a2d1c0b9e8f",
"timestamp": "2026-11-03T09:41:12.000Z",
"path": "/v1/find-email",
"error": "Unauthorized"
}{
"statusCode": 401,
"message": "RATE_LIMIT_EXCEEDED",
"traceId": "4f1c2b7e9a0d4c3b8e6f5a2d1c0b9e8f",
"timestamp": "2026-11-03T09:41:12.000Z",
"path": "/v1/find-email",
"limit": 10,
"windowSeconds": 60,
"retryAfterSeconds": 6,
"error": "Unauthorized"
}Authorizations
Your API key, from the API keys page of the app.
Path Parameters
The campaign's UUID.
Example:
"019f2504-58b8-77ec-9c3f-54f5d6df733e"
Body
application/json
Example:
"john.doe@example.com"
Id of an existing lead in this campaign to update. The lead keeps its id and history even when the email changes, and omitted names, company and profile fields are carried over from the lead. Without it the lead is matched by email.
Example:
42
Example:
"John"
Example:
"Doe"
Example:
"Acme Inc."
Pause lead processing until this date
Example:
"2026-06-30T00:00:00.000Z"
Show child attributes
Show child attributes
Example:
[
{
"name": "jobTitle",
"value": "Software Engineer"
},
{ "name": "country", "value": "Pakistan" }
]