Search Docs…

Search Docs…

Leads

Update Lead Attributes

🚨 Important Notice – Read This First

Platforms like HeyReach, Prosp, Aimfox and other LinkedIn automation tools automatically send rich attributes into Outreach Magic, including:

  • LinkedIn profile URL

  • LinkedIn Sales Navigator URL

  • LinkedIn ID

  • LinkedIn headline

  • LinkedIn job title

  • LinkedIn bio/about section

These fields are automatically mapped without needing this API call.

You only need update_attributes if:

  • you want to override these values

  • you want to add additional enrichment from tools like Clay, Apollo, ZoomInfo, Clearbit, Lusha, etc.

  • you want to populate workspace-wide attributes like:

    • import_name

    • list_source

    • exclusion_reason

    • icp

Workspace-wide attributes apply across your entire workspace and require workspace_id in the request.

Outreach Magic API – update_attributes (Quickstart & Reference)

Upsert Lead and Company attributes with a single call. Send one update object or a batch array.

Use Clay?

Download a ready-to-use Clay Starter Pack: 👉 https://outreachmagic.io/clay-starter-pack

Endpoint & Headers

POST https://api.outreachmagic.io/v1/events

Headers

  • x-api-key: {{YOUR_API_KEY}}

  • content-type: application/json

What This Call Does

Creates an update_attributes event used to update:

Lead Attributes

Matched by:

  • email

  • unified_lead_id

  • LinkedIn URL

  • LinkedIn Sales Navigator URL

  • LinkedIn ID

Company Attributes

Matched by:

  • domain

  • unified_company_id

  • company LinkedIn URL

Workspace-Wide Attributes (Require workspace_id)

These apply across your entire workspace:

  • import_name

  • list_source

  • exclusion_reason

  • icp

If you include any of the fields above, you must include workspace_id.

Minimal Request (Single)
{
  "event": "update_attributes",
  "platform": "clay",
  "workspace_id": "65f1a2b3c4d5e6f7890a1b2c",
  "lead_email": "[email protected]",
  "company_domain": "example.co",
  "lead_first_name": "Jane",
  "company_name": "Example Co"
}
Batch Request (Multiple)
[
  {
    "event": "update_attributes",
    "platform": "clay",
    "workspace_id": "65f1a2b3c4d5e6f7890a1b2c",
    "lead_email": "[email protected]",
    "company_domain": "example.co",
    "lead_first_name": "Jane",
    "company_name": "Example Co"
  },
  {
    "event": "update_attributes",
    "platform": "clay",
    "workspace_id": "65f1a2b3c4d5e6f7890a1b2c",
    "lead_email": "[email protected]",
    "company_domain": "sample.io",
    "lead_first_name": "Alex",
    "company_name": "Sample IO"
  }
]
Full Example – All Fields

JSONC below is for documentation only. Clay, Postman, and cURL require pure JSON.

JSONC (commented)
{
  "event": "update_attributes",
  "platform": "clay",

  // Workspace-wide attributes
  // REQUIRED: workspace_id if any of these are included
  "workspace_id": "65f1a2b3c4d5e6f7890a1b2c",
  "import_name": "Sample Import - ICP 1",
  "list_source": "apollo",
  "exclusion_reason": "existing_customer",
  "icp": "ICP 1",

  // Lead identifiers
  // LinkedIn automation tools (HeyReach, Prosp) usually provide ALL of these automatically:
  "unified_lead_id": "65f1a2b3c4d5e6f7890a1d3e",
  "lead_email": "[email protected]",
  "lead_linkedin_url": "https://www.linkedin.com/in/sample-profile/",
  "lead_sales_navigator_url": "https://www.linkedin.com/sales/people/1234567890",
  "lead_linkedin_id": "sample-linkedin-id",

  // Lead attributes (optional enrichment or overrides)
  "lead_first_name": "Jane",
  "lead_last_name": "Doe",
  "lead_full_name": "Jane Doe",
  "lead_country": "United States",
  "lead_job_title": "Head of Operations",
  "lead_seniority": "director",
  "lead_function": "Operations",
  "lead_linkedin_headline": "Ops leader focused on scalable systems",
  "lead_reporting_location": "United States",

  // Company identifiers
  "unified_company_id": "65f1a2b3c4d5e6f7890a1e4f",
  "company_domain": "example.co",
  "company_linkedin_url": "https://www.linkedin.com/company/example-co/",

  // Company attributes
  "company_name": "Example Co",
  "company_country": "United States",
  "company_employee_range": "51–200 employees",
  "company_industry": "Software",
  "company_description": "Sample description",
  "company_employee_count": "123",

  // Normalized overrides
  "company_normalized_name": "ExampleCo",
  "company_normalized_industry": "Software & Services"
}
Pure JSON (tool-ready)
{
  "event": "update_attributes",
  "platform": "clay",
  "workspace_id": "65f1a2b3c4d5e6f7890a1b2c",
  "import_name": "Sample Import - ICP 1",
  "list_source": "apollo",
  "exclusion_reason": "existing_customer",
  "icp": "ICP 1",
  "unified_lead_id": "65f1a2b3c4d5e6f7890a1d3e",
  "lead_email": "[email protected]",
  "lead_linkedin_url": "https://www.linkedin.com/in/sample-profile/",
  "lead_sales_navigator_url": "https://www.linkedin.com/sales/people/1234567890",
  "lead_linkedin_id": "sample-linkedin-id",
  "lead_first_name": "Jane",
  "lead_last_name": "Doe",
  "lead_full_name": "Jane Doe",
  "lead_country": "United States",
  "lead_job_title": "Head of Operations",
  "lead_seniority": "director",
  "lead_function": "Operations",
  "lead_linkedin_headline": "Ops leader focused on scalable systems",
  "lead_reporting_location": "United States",
  "unified_company_id": "65f1a2b3c4d5e6f7890a1e4f",
  "company_domain": "example.co",
  "company_linkedin_url": "https://www.linkedin.com/company/example-co/",
  "company_name": "Example Co",
  "company_country": "United States",
  "company_employee_range": "51-200 employees",
  "company_industry": "Software",
  "company_description": "Sample description",
  "company_employee_count": "123",
  "company_normalized_name": "ExampleCo",
  "company_normalized_industry": "Software & Services"
}
Responses
Success
{
  "errors": { "count": 0, "details": [] },
  "success": 1,
  "total": 1
}
Invalid API Key
{
  "error": "Invalid API key provided"
}
Validation Error
{
  "errors": {
    "count": 1,
    "details": [
      {
        "index": 0,
        "error": [
          {
            "msg": "Value error: workspace_id is required if any of ['import_name','list_source','exclusion_reason','icp'] is present",
            "type": "value_error"
          }
        ]
      }
    ]
  },
  "success": 0,
  "total": 1
}
Rules & Matching Behavior
Workspace-Wide Attributes

Require workspace_id whenever using:

  • import_name

  • list_source

  • exclusion_reason

  • icp

Lead Matching Priority

  1. unified_lead_id

  2. lead_email

  3. lead_linkedin_url

  4. lead_sales_navigator_url

  5. lead_linkedin_id

Company Matching Priority

  1. unified_company_id

  2. company_domain

  3. company_linkedin_url

Field Reference
Core

  • event (required)

  • platform (optional)

Workspace-Wide Attributes

  • workspace_id (required when using the fields below)

  • import_name

  • list_source

  • exclusion_reason

  • icp

Lead Identification

  • email

  • LinkedIn URL

  • Sales Navigator URL

  • LinkedIn ID

  • unified_lead_id

Lead Attributes

  • name fields

  • title

  • seniority

  • function

  • headline

  • reporting location

  • LinkedIn fields are auto-populated when using HeyReach or Prosp

Company Fields

  • domain

  • LinkedIn URL

  • employee count

  • industry

  • description, etc.

Clay / Postman Notes

  • Use pure JSON

  • Must include your real API key

  • Batch requests must be an array

Setup Clay - Send Lead Attributes, Lead Status & LinkedIn Status

Setup Clay - Send Lead Attributes, Lead Status & LinkedIn Status

Setup Clay - Send Lead Attributes, Lead Status & LinkedIn Status

Setup HeyReach Webhook

Setup HeyReach Webhook

Setup HeyReach Webhook