Sync Leads from CRM - Naturalead API

Overview

The lead sync API lets you push leads from your CRM (HubSpot, Salesforce, Pipedrive, or any custom system) into Naturalead. It supports idempotent upserts using an external lead_id, so you can run periodic syncs without creating duplicates.

Idempotent Upserts

Use your CRM’s lead ID as the external identifier. Re-syncing the same lead updates it instead of creating a duplicate.

Bulk Operations

Sync up to 100 leads per request. The API handles partial failures gracefully.

Authentication

Authenticate sync requests with an API key.

curl -H "X-API-Key: nl_live_your_api_key_here" ...

Sync requests require an API key with the leads:sync_create scope. Create one in Settings > API Keys in the dashboard.

Using External lead_id for Idempotent Upserts

Every lead in the sync payload can include a lead_id field that maps to your CRM’s unique identifier. When Naturalead receives a lead with a lead_id that already exists in your account, it updates the existing lead instead of creating a new one. This makes your sync operations idempotent — running the same sync twice produces the same result.

Bulk Sync Example

Send an array of leads to the sync endpoint. Each lead should include a lead_id from your CRM.

curl -X POST https://api.naturalead.ai/api/leads/sync \
  -H "X-API-Key: nl_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "hubspot",
    "leads": [
      {
        "lead_id": "hs_12345",
        "name": "Alice Johnson",
        "phone": "+14155551234",
        "email": "[email protected]",
        "customFields": {
          "company": "Acme Corp",
          "deal_stage": "discovery",
          "deal_value": 50000
        },
        "tags": ["enterprise", "inbound"]
      },
      {
        "lead_id": "hs_12346",
        "name": "Bob Smith",
        "phone": "+14155555678",
        "email": "[email protected]",
        "customFields": {
          "company": "Globex Inc",
          "deal_stage": "proposal",
          "deal_value": 25000
        },
        "tags": ["smb", "outbound"]
      }
    ]
  }'

import requests

url = "https://api.naturalead.ai/api/leads/sync"
headers = {
    "X-API-Key": "nl_live_your_api_key_here",
    "Content-Type": "application/json",
}
payload = {
    "source": "hubspot",
    "leads": [
        {
            "lead_id": "hs_12345",
            "name": "Alice Johnson",
            "phone": "+14155551234",
            "email": "[email protected]",
            "customFields": {
                "company": "Acme Corp",
                "deal_stage": "discovery",
                "deal_value": 50000,
            },
            "tags": ["enterprise", "inbound"],
        },
        {
            "lead_id": "hs_12346",
            "name": "Bob Smith",
            "phone": "+14155555678",
            "email": "[email protected]",
            "customFields": {
                "company": "Globex Inc",
                "deal_stage": "proposal",
                "deal_value": 25000,
            },
            "tags": ["smb", "outbound"],
        },
    ],
}

response = requests.post(url, headers=headers, json=payload)
result = response.json()

print(f"Created: {result['created']}")
print(f"Updated: {result['updated']}")
print(f"Failed: {result['failed']}")

const response = await fetch("https://api.naturalead.ai/api/leads/sync", {
  method: "POST",
  headers: {
    "X-API-Key": "nl_live_your_api_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    source: "hubspot",
    leads: [
      {
        lead_id: "hs_12345",
        name: "Alice Johnson",
        phone: "+14155551234",
        email: "[email protected]",
        customFields: {
          company: "Acme Corp",
          deal_stage: "discovery",
          deal_value: 50000,
        },
        tags: ["enterprise", "inbound"],
      },
      {
        lead_id: "hs_12346",
        name: "Bob Smith",
        phone: "+14155555678",
        email: "[email protected]",
        customFields: {
          company: "Globex Inc",
          deal_stage: "proposal",
          deal_value: 25000,
        },
        tags: ["smb", "outbound"],
      },
    ],
  }),
});

const result = await response.json();
console.log("Created:", result.created);
console.log("Updated:", result.updated);
console.log("Failed:", result.failed);

Syncing Incomplete Records

Only lead_id and phone are required. CRM records that are missing a name, an email address, or both are accepted and synced as-is.

Field	Required	Behavior when missing
`lead_id`	Yes	The lead is rejected.
`phone`	Yes	The lead is rejected.
`name`	No	The lead is stored without a name. The agent opens the conversation without addressing the lead by name, and the dashboard shows the lead as unnamed.
`email`	No	The lead is reachable on WhatsApp and Telegram. Email campaigns skip it.
`source`	No	Defaults to `sync`.

On a re-sync, a field you omit keeps whatever value is already stored, so a partial payload never overwrites data with blanks. To clear a stored name or email, send it explicitly as "" or null.

{
  "leads": [
    {
      "lead_id": "hs_12348",
      "phone": "+14155559876"
    },
    {
      "lead_id": "hs_12349",
      "phone": "+14155551111",
      "email": null
    }
  ]
}

Handling Partial Failures

When syncing multiple leads, some may succeed while others fail validation. The API does not roll back successful operations when others fail. Instead, it returns a detailed breakdown.

{
  "created": 1,
  "updated": 1,
  "failed": 1,
  "errors": [
    {
      "index": 2,
      "lead_id": "hs_12347",
      "error": "Invalid phone number format"
    }
  ]
}

Always check the errors array in the response. A 200 status code does not mean every lead was synced successfully — it means the request was processed, and the response contains the outcome for each lead.

Recommended error handling strategy:

Log all entries from the errors array with their lead_id for investigation.
Fix the invalid data in your CRM.
Re-sync only the failed leads in the next run.

Bulk Delete for Synced Leads

To remove leads that were deleted in your CRM, use the bulk delete endpoint with the external lead_id values.

curl -X DELETE https://api.naturalead.ai/api/leads/sync \
  -H "X-API-Key: nl_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "hubspot",
    "lead_ids": ["hs_12345", "hs_12346"]
  }'

import requests

url = "https://api.naturalead.ai/api/leads/sync"
headers = {
    "X-API-Key": "nl_live_your_api_key_here",
    "Content-Type": "application/json",
}
payload = {
    "source": "hubspot",
    "lead_ids": ["hs_12345", "hs_12346"],
}

response = requests.delete(url, headers=headers, json=payload)
result = response.json()
print(f"Deleted: {result['deleted']}")

const response = await fetch("https://api.naturalead.ai/api/leads/sync", {
  method: "DELETE",
  headers: {
    "X-API-Key": "nl_live_your_api_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    source: "hubspot",
    lead_ids: ["hs_12345", "hs_12346"],
  }),
});

const result = await response.json();
console.log("Deleted:", result.deleted);

Rate Limit Considerations

The sync API has a dedicated rate limit to protect system stability.

Limit	Value
Sync requests per minute	50
Leads per sync request	100
Maximum leads per minute	5,000

If you exceed the rate limit, the API returns a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait before retrying.

For large initial imports (more than 5,000 leads), break the sync into batches:

import time
import requests

BATCH_SIZE = 100
DELAY_BETWEEN_BATCHES = 1.5  # seconds

def sync_leads_in_batches(all_leads):
    for i in range(0, len(all_leads), BATCH_SIZE):
        batch = all_leads[i:i + BATCH_SIZE]
        response = requests.post(
            "https://api.naturalead.ai/api/leads/sync",
            headers={
                "X-API-Key": "nl_live_your_api_key_here",
                "Content-Type": "application/json",
            },
            json={"source": "hubspot", "leads": batch},
        )

        result = response.json()
        print(f"Batch {i // BATCH_SIZE + 1}: "
              f"created={result['created']}, "
              f"updated={result['updated']}, "
              f"failed={result['failed']}")

        if response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 60))
            print(f"Rate limited. Waiting {retry_after}s...")
            time.sleep(retry_after)
        else:
            time.sleep(DELAY_BETWEEN_BATCHES)

Best Practices for Periodic Sync

Use External lead_id Consistently

Always include the CRM’s unique lead identifier as lead_id. This is the key that makes upserts idempotent. Never omit it, or you risk creating duplicates.

Sync Incrementally

Rather than syncing your entire CRM on every run, track the last sync timestamp and only send leads that were created or modified since then. This reduces API calls and processing time.

Handle Deletes Separately

After syncing new and updated leads, query your CRM for recently deleted records and send those to the bulk delete endpoint.

Schedule During Off-Peak Hours

If you are syncing large volumes, schedule your sync jobs during off-peak hours to avoid competing with real-time conversation traffic for rate limit capacity.

Monitor and Alert on Failures

Log every sync response and set up alerts when the failed count exceeds a threshold. Persistent failures often indicate data quality issues in the CRM that should be resolved at the source.

For real-time sync (pushing leads as they are created in your CRM), consider using your CRM’s webhook or event system to trigger individual lead creation via POST /api/leads instead of the bulk sync endpoint.

​Overview

Idempotent Upserts

Bulk Operations

​Authentication

​Using External lead_id for Idempotent Upserts

​Bulk Sync Example

​Syncing Incomplete Records

​Handling Partial Failures

​Bulk Delete for Synced Leads

​Rate Limit Considerations

​Best Practices for Periodic Sync

Overview

Authentication

Using External lead_id for Idempotent Upserts

Bulk Sync Example

Syncing Incomplete Records

Handling Partial Failures

Bulk Delete for Synced Leads

Rate Limit Considerations

Best Practices for Periodic Sync