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

# Create a bulk search

> Start a reverse lookup for multiple emails in a single request

## Authentication

<ParamField header="x-api-key" type="string" required>
  Your API key
</ParamField>

## Body

<ParamField body="emails" type="string[]" required>
  List of email addresses to search.

  * Minimum: 1 email
  * Maximum: 5000 emails
  * Invalid emails are automatically filtered out

  **Example:** `["john@company.com", "jane@startup.io"]`
</ParamField>

<ParamField body="custom" type="any">
  Custom data to associate with this bulk search. Will be returned in the webhook if configured.
</ParamField>

<ParamField body="settings" type="object">
  Optional search configuration.

  <Expandable title="Properties">
    <ParamField body="settings.webhooks" type="string[]">
      List of URLs to notify when the bulk search is complete.
    </ParamField>
  </Expandable>
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.reverselooker.com/reverse-contact/bulk \
    -H "Content-Type: application/json" \
    -H "x-api-key: your_api_key" \
    -d '{
      "emails": [
        "john.doe@company.com",
        "jane.smith@startup.io",
        "bob.wilson@enterprise.co"
      ]
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.reverselooker.com/reverse-contact/bulk', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'your_api_key'
    },
    body: JSON.stringify({
      emails: [
        'john.doe@company.com',
        'jane.smith@startup.io',
        'bob.wilson@enterprise.co'
      ]
    })
  });

  const data = await response.json();
  console.log(data.id); // Use this ID to retrieve results
  console.log(data.credits_used); // 150 (3 emails x 50 credits)
  ```

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

  response = requests.post(
      'https://api.reverselooker.com/reverse-contact/bulk',
      headers={
          'Content-Type': 'application/json',
          'x-api-key': 'your_api_key'
      },
      json={
          'emails': [
              'john.doe@company.com',
              'jane.smith@startup.io',
              'bob.wilson@enterprise.co'
          ]
      }
  )

  data = response.json()
  print(data['id'])  # Use this ID to retrieve results
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "number_of_searches": 3,
    "credits_used": 150,
    "message": "Bulk reverse contact search operating"
  }
  ```

  ```json 400 - Invalid payload theme={null}
  {
    "error": "Missing or invalid payload"
  }
  ```

  ```json 400 - Too many emails theme={null}
  {
    "error": "Maximum 5000 emails per request"
  }
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "error": "Invalid API key"
  }
  ```

  ```json 422 - Insufficient credits theme={null}
  {
    "error": "Insufficient balance",
    "available": 100,
    "required": 150
  }
  ```
</ResponseExample>

## Response

<ResponseField name="id" type="string" required>
  Unique bulk search identifier. Use it with `GET /reverse-contact/bulk` to retrieve results.
</ResponseField>

<ResponseField name="number_of_searches" type="number" required>
  Number of valid emails that will be searched (after filtering invalid emails).
</ResponseField>

<ResponseField name="credits_used" type="number" required>
  Total credits consumed (50 × number of emails).
</ResponseField>

<ResponseField name="message" type="string" required>
  Confirmation message.
</ResponseField>

## Email validation

Emails are validated before processing:

* Invalid emails are automatically excluded
* Emails are normalized to lowercase
* If no valid emails remain after filtering, a 400 error is returned

<Tip>
  For large volumes, split your requests into batches of 5000 emails maximum.
</Tip>

## Next step

<Card title="Retrieve results" icon="magnifying-glass" href="/api-reference/get-bulk">
  Use the returned ID to track progress and get the found profiles.
</Card>