Update a lead

PATCH/v1/leads/{lead_id}

Scope: leads:write

Updates the fields you send and leaves the rest unchanged. An email is saved trimmed and lowercased. Changing the email or LinkedIn URL to one another lead already has answers 409 LEAD_ALREADY_EXISTS, and to one on your do-not-contact list answers 409 LEAD_SUPPRESSED.

Fields sent as null are ignored, so this endpoint can't clear a field. custom_fields replaces the lead's whole custom fields object rather than merging into it.

Headers

AuthorizationstringRequired
Bearer followed by a space and your API key, for example Bearer vk_….

Path parameters

lead_idstring · uuidRequired
ID of the lead.

Request body

annual_revenueinteger or null
Company annual revenue in dollars
≥ 0Example 5000000
companystring or null
Company name
at most 2,000 charactersExample "Acme Corp"
company_websitestring or null
Lead's company website URL
at most 2,000 charactersExample "https://acmecorp.com"
custom_fieldsobject or null
Custom fields as key-value pairs
emailstring · email or null
Lead's email address
at most 2,000 charactersExample "sarah.johnson@acmecorp.com"
employeesinteger or null
Number of employees at the company
≥ 0Example 150
first_namestring or null
Lead's first name
at most 2,000 charactersExample "Sarah"
industrystring or null
Industry sector
at most 2,000 charactersExample "Technology"
last_namestring or null
Lead's last name
at most 2,000 charactersExample "Johnson"
linkedin_urlstring or null
Lead's LinkedIn profile URL
at most 2,000 charactersExample "https://linkedin.com/in/sarahjohnson"
phone_numberstring or null
Phone number
at most 2,000 charactersExample "+1-555-123-4567"
qualification_scorenumber or null
Lead qualification score (0-100)
Example 85.5
titlestring or null
Job title
at most 2,000 charactersExample "VP of Sales"

Response

200

messagestringRequired
Success message
leadobjectRequired
Updated lead details
Show 17 child attributesHide child attributes
- idstringRequired
  Lead UUID
  Example "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
- created_atstring · date-timeRequired
  When the lead was created
  Example "2024-01-15T10:30:00+00:00"
- annual_revenueinteger or null
  Company annual revenue in dollars
  Example 5000000
- companystring or null
  Company name
  Example "Acme Corp"
- company_websitestring or null
  Lead's company website URL
  Example "https://acmecorp.com"
- custom_fieldsobject or null
  Custom fields as key-value pairs
- delivered_atstring · date-time or null
  When a lead-database result was delivered to your workspace; null for leads from other sources
  Example "2026-09-01T09:00:00+00:00"
- emailstring or null
  Lead's email address
  Example "sarah.johnson@acmecorp.com"
- employeesinteger or null
  Number of employees at the company
  Example 150
- first_namestring or null
  Lead's first name
  Example "Sarah"
- industrystring or null
  Industry sector
  Example "Technology"
- last_namestring or null
  Lead's last name
  Example "Johnson"
- linkedin_urlstring or null
  Lead's LinkedIn profile URL
  Example "https://linkedin.com/in/sarahjohnson"
- phone_numberstring or null
  Phone number
  Example "+1-555-123-4567"
- qualification_scorenumber or null
  Lead qualification score (0-100)
  Example 85.5
- sourcestring or null
  Where the lead came from: lead_database for a licensed lead-database result, csv for an upload, manual for one entered by hand, linkedin_search for a LinkedIn search; null for leads recorded before sources were tracked
  Example "lead_database"
- titlestring or null
  Job title
  Example "VP of Sales"
successboolean
Default true

Errors

Errors share one JSON body: success, error, message, optional details, and request_id.

Status	Code	Meaning
400	VALIDATION_ERROR	The request didn't match the endpoint's schema: a missing or malformed field, a bad query parameter, or a value out of range. `details.errors` lists each failing field with its `field`, `message` and `type`.
400	NO_UPDATES	The update request contained no fields to change.
401	UNAUTHORIZED	The `Authorization` header is missing or malformed, or the API key is unknown or has been deactivated.
401	API_KEY_EXPIRED	The API key is past its expiry date. Create a new key in the Victoria AI app.
403	INSUFFICIENT_SCOPE	The API key doesn't have the scope this endpoint requires, such as `leads:write`.
403	ORGANIZATION_DEACTIVATED	The organization that owns this API key has been deactivated.
404	LEAD_NOT_FOUND	No lead with this ID exists in your organization.
404	NOT_FOUND	No endpoint matches the path. A resource ID in the path that isn't a valid UUID also answers `NOT_FOUND`.
409	LEAD_ALREADY_EXISTS	A lead with the same email or LinkedIn URL already exists in your organization. From Create a lead, this means the request named no `campaign_id` to enrol the existing lead in, or raced an identical request. Changing a lead's email or LinkedIn URL to another lead's answers it too. When it's known, `details.existing_lead_id` identifies the existing lead.
409	LEAD_SUPPRESSED	The contact is on your organization's do-not-contact list, so the lead wasn't created, enrolled or updated. `details.suppressed_by` is `email`, `domain` or `linkedin_url`, and `details.value` is the entry that matched.
413	PAYLOAD_TOO_LARGE	The request body is larger than 1 MB.
429	RATE_LIMITED	Too many requests for this API key: more than 100 a minute to one endpoint, or 600 a minute in total. Retry after the number of seconds in the `Retry-After` header. See Rate limits.
500	INTERNAL_ERROR	Something failed on our side. The response never includes internal details; quote its `request_id` when you contact support.
503	UPSTREAM_TIMEOUT	A service the API depends on timed out. The request is safe to retry.
503	AUTH_UNAVAILABLE	The API key couldn't be checked because the authentication service was unavailable. The request is safe to retry.

Response headers

Header	Description
`X-Request-ID`	Correlation ID for the request, also returned as `request_id` in error bodies. Send your own `X-Request-ID`, up to 128 letters, digits, `.`, `_`, `:` or `-`, and it's used instead.
`RateLimit-Limit`	Requests allowed to this endpoint per minute.
`RateLimit-Remaining`	Requests you can still send to this endpoint right now.
`RateLimit-Reset`	Seconds until the endpoint's full limit is available again.
`Retry-After`	On a `429`: seconds to wait before retrying.

Request

curl -X PATCH "https://api.versionseven.ai/v1/leads/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer $VICTORIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "annual_revenue": 5000000,
  "company": "Acme Corp",
  "company_website": "https://acmecorp.com",
  "custom_fields": {
    "source": "conference"
  },
  "email": "sarah.johnson@acmecorp.com",
  "employees": 150,
  "first_name": "Sarah",
  "industry": "Technology",
  "last_name": "Johnson",
  "linkedin_url": "https://linkedin.com/in/sarahjohnson",
  "phone_number": "+1-555-123-4567",
  "qualification_score": 85.5,
  "title": "VP of Sales"
}'

const response = await fetch("https://api.versionseven.ai/v1/leads/a1b2c3d4-e5f6-7890-abcd-ef1234567890", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.VICTORIA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "annual_revenue": 5000000,
    "company": "Acme Corp",
    "company_website": "https://acmecorp.com",
    "custom_fields": {
      "source": "conference"
    },
    "email": "sarah.johnson@acmecorp.com",
    "employees": 150,
    "first_name": "Sarah",
    "industry": "Technology",
    "last_name": "Johnson",
    "linkedin_url": "https://linkedin.com/in/sarahjohnson",
    "phone_number": "+1-555-123-4567",
    "qualification_score": 85.5,
    "title": "VP of Sales"
  }),
});

const data = await response.json();

import os

import requests

response = requests.patch(
    "https://api.versionseven.ai/v1/leads/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    headers={
        "Authorization": f"Bearer {os.environ['VICTORIA_API_KEY']}",
    },
    json={
        "annual_revenue": 5000000,
        "company": "Acme Corp",
        "company_website": "https://acmecorp.com",
        "custom_fields": {
            "source": "conference",
        },
        "email": "sarah.johnson@acmecorp.com",
        "employees": 150,
        "first_name": "Sarah",
        "industry": "Technology",
        "last_name": "Johnson",
        "linkedin_url": "https://linkedin.com/in/sarahjohnson",
        "phone_number": "+1-555-123-4567",
        "qualification_score": 85.5,
        "title": "VP of Sales",
    },
)
data = response.json()

Response

{
  "message": "string",
  "lead": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "created_at": "2024-01-15T10:30:00+00:00",
    "annual_revenue": 5000000,
    "company": "Acme Corp",
    "company_website": "https://acmecorp.com",
    "custom_fields": {},
    "delivered_at": "2026-09-01T09:00:00+00:00",
    "email": "sarah.johnson@acmecorp.com",
    "employees": 150,
    "first_name": "Sarah",
    "industry": "Technology",
    "last_name": "Johnson",
    "linkedin_url": "https://linkedin.com/in/sarahjohnson",
    "phone_number": "+1-555-123-4567",
    "qualification_score": 85.5,
    "source": "lead_database",
    "title": "VP of Sales"
  },
  "success": true
}