> ## Documentation Index
> Fetch the complete documentation index at: https://docs.leadlex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Save Prospects

> Save prospects from search results to your CRM as contacts

## Request

### Headers

```
Authorization: Bearer wbk_your_api_key_here
Content-Type: application/json
```

### Body Parameters

<ParamField body="prospects" type="array" required>
  Array of prospect objects to save

  <Expandable title="Prospect object">
    <ParamField body="name" type="string" required>
      Full name
    </ParamField>

    <ParamField body="email" type="string">
      Email address
    </ParamField>

    <ParamField body="title" type="string">
      Job title
    </ParamField>

    <ParamField body="company_name" type="string">
      Company name
    </ParamField>

    <ParamField body="linkedin_url" type="string">
      LinkedIn profile URL
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="list_id" type="string">
  Optional: UUID of list to add contacts to
</ParamField>

## Response

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="created" type="integer">
      Number of new contacts created
    </ResponseField>

    <ResponseField name="contacts" type="array">
      Array of created contact objects

      <Expandable title="Contact object">
        <ResponseField name="id" type="string">
          Contact UUID
        </ResponseField>

        <ResponseField name="full_name" type="string">
          Contact name
        </ResponseField>

        <ResponseField name="email" type="string">
          Email address
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST \
    https://data.leadlex.com/functions/v1/api-gateway/v1/prospects/save \
    -H "Authorization: Bearer wbk_your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "prospects": [
        {
          "name": "John Smith",
          "email": "john@example.com",
          "title": "CEO",
          "company_name": "Acme Legal Corp",
          "linkedin_url": "https://linkedin.com/in/johnsmith"
        }
      ],
      "list_id": "abc-123"
    }'
  ```

  ```python Python theme={null}
  import requests

  API_KEY = "wbk_your_api_key_here"
  BASE_URL = "https://data.leadlex.com/functions/v1/api-gateway"

  headers = {
      "Authorization": f"Bearer {API_KEY}",
      "Content-Type": "application/json"
  }

  # Save prospects from search results
  prospects_to_save = [
      {
          "name": "John Smith",
          "email": "john@example.com",
          "title": "CEO",
          "company_name": "Acme Legal Corp",
          "linkedin_url": "https://linkedin.com/in/johnsmith"
      }
  ]

  data = {
      "prospects": prospects_to_save,
      "list_id": "abc-123"  # Optional
  }

  response = requests.post(f"{BASE_URL}/v1/prospects/save", headers=headers, json=data)
  result = response.json()["data"]
  print(f"Created {result['created']} contacts")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://data.leadlex.com/functions/v1/api-gateway/v1/prospects/save',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer wbk_your_api_key_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        prospects: [
          {
            name: 'John Smith',
            email: 'john@example.com',
            title: 'CEO',
            company_name: 'Acme Legal Corp',
            linkedin_url: 'https://linkedin.com/in/johnsmith'
          }
        ],
        list_id: 'abc-123'
      })
    }
  );

  const { data } = await response.json();
  console.log(`Created ${data.created} contacts`);
  ```
</CodeGroup>

### Example Response

```json theme={null}
{
  "data": {
    "created": 1,
    "contacts": [
      {
        "id": "789e0123-e45b-67c8-a901-234567890abc",
        "full_name": "John Smith",
        "email": "john@example.com",
        "job_title": "CEO",
        "company_name": "Acme Legal Corp"
      }
    ]
  }
}
```

## Complete Workflow Example

Search for prospects, then save them:

<CodeGroup>
  ```python Python theme={null}
  # Step 1: Search for prospects
  search_response = requests.post(
      f"{BASE_URL}/v1/prospects/search",
      headers=headers,
      json={
          "query": {
              "person_titles": ["CEO"],
              "organization_industries": ["Legal"]
          },
          "per_page": 50
      }
  )
  prospects = search_response.json()["data"]["prospects"]

  # Step 2: Create a list
  list_response = requests.post(
      f"{BASE_URL}/v1/lists",
      headers=headers,
      json={"name": "Law Firm CEOs", "description": "Q1 Campaign"}
  )
  list_id = list_response.json()["data"]["id"]

  # Step 3: Save prospects to CRM and list
  save_response = requests.post(
      f"{BASE_URL}/v1/prospects/save",
      headers=headers,
      json={
          "prospects": prospects,
          "list_id": list_id
      }
  )

  result = save_response.json()["data"]
  print(f"Saved {result['created']} contacts to list {list_id}")
  ```

  ```javascript JavaScript theme={null}
  // Step 1: Search for prospects
  const searchResponse = await fetch(`${BASE_URL}/v1/prospects/search`, {
    method: 'POST',
    headers: { ...headers, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      query: {
        person_titles: ['CEO'],
        organization_industries: ['Legal']
      },
      per_page: 50
    })
  });
  const { data: { prospects } } = await searchResponse.json();

  // Step 2: Create a list
  const listResponse = await fetch(`${BASE_URL}/v1/lists`, {
    method: 'POST',
    headers: { ...headers, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Law Firm CEOs',
      description: 'Q1 Campaign'
    })
  });
  const { data: { id: listId } } = await listResponse.json();

  // Step 3: Save prospects
  const saveResponse = await fetch(`${BASE_URL}/v1/prospects/save`, {
    method: 'POST',
    headers: { ...headers, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      prospects,
      list_id: listId
    })
  });

  const { data: result } = await saveResponse.json();
  console.log(`Saved ${result.created} contacts to list ${listId}`);
  ```
</CodeGroup>

## Duplicate Handling

<Note>
  The API automatically detects duplicate contacts based on email address. If a contact already exists, it will be skipped (not counted in `created`).
</Note>

## Errors

| Status | Code                       | Description                     |
| ------ | -------------------------- | ------------------------------- |
| 400    | `validation_error`         | Invalid prospect data           |
| 401    | `invalid_key`              | Invalid API key                 |
| 403    | `insufficient_permissions` | Missing `write` permission      |
| 404    | `not_found`                | List ID not found (if provided) |
| 429    | `rate_limited`             | Rate limit exceeded             |