> ## 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.

# Retrieve a bulk search

> Get the results of a bulk search

## Authentication

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

## Query Parameters

<ParamField query="id" type="string" required>
  The bulk search identifier returned by `POST /reverse-contact/bulk`.

  **Example:** `550e8400-e29b-41d4-a716-446655440000`
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.reverselooker.com/reverse-contact/bulk?id=550e8400-e29b-41d4-a716-446655440000" \
    -H "x-api-key: your_api_key"
  ```

  ```javascript Node.js theme={null}
  const bulkId = '550e8400-e29b-41d4-a716-446655440000';

  const response = await fetch(
    `https://api.reverselooker.com/reverse-contact/bulk?id=${bulkId}`,
    {
      headers: {
        'x-api-key': 'your_api_key'
      }
    }
  );

  const data = await response.json();

  console.log(`Progress: ${data.number_finished}/${data.number_requested}`);

  if (data.status === 'completed') {
    const foundProfiles = data.results.filter(r => r.qualification === 'found');
    console.log(`${foundProfiles.length} profiles found`);
  }
  ```

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

  bulk_id = '550e8400-e29b-41d4-a716-446655440000'

  response = requests.get(
      f'https://api.reverselooker.com/reverse-contact/bulk?id={bulk_id}',
      headers={
          'x-api-key': 'your_api_key'
      }
  )

  data = response.json()

  print(f"Progress: {data['number_finished']}/{data['number_requested']}")

  if data['status'] == 'completed':
      found = [r for r in data['results'] if r['qualification'] == 'found']
      print(f"{len(found)} profiles found")
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - In progress theme={null}
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "created_at": "2024-01-15T10:30:00Z",
    "last_update": "2024-01-15T10:31:45Z",
    "number_requested": 100,
    "number_finished": 45,
    "status": "ongoing",
    "results": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "email": "john.doe@company.com",
        "qualification": "found",
        "linkedin_url": "https://linkedin.com/in/johndoe",
        "full_name": "John Doe",
        "headline": "Senior Software Engineer",
        "company_name": "Company Inc.",
        "location": "San Francisco, CA"
      },
      {
        "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
        "email": "jane.smith@startup.io",
        "qualification": "not_found",
        "linkedin_url": null,
        "full_name": null,
        "headline": null,
        "company_name": null,
        "location": null
      },
      {
        "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
        "email": "bob.wilson@enterprise.co",
        "qualification": "ongoing",
        "linkedin_url": null,
        "full_name": null,
        "headline": null,
        "company_name": null,
        "location": null
      }
    ]
  }
  ```

  ```json 200 - Completed theme={null}
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "created_at": "2024-01-15T10:30:00Z",
    "last_update": "2024-01-15T10:35:00Z",
    "number_requested": 100,
    "number_finished": 100,
    "status": "completed",
    "results": [...]
  }
  ```

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

  ```json 404 - Search not found theme={null}
  {
    "error": "Bulk search not found"
  }
  ```
</ResponseExample>

## Response

<ResponseField name="id" type="string" required>
  Unique bulk search identifier.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  Search creation date (ISO 8601 format).
</ResponseField>

<ResponseField name="last_update" type="string" required>
  Last update date (ISO 8601 format).
</ResponseField>

<ResponseField name="number_requested" type="number" required>
  Total number of emails in the initial request.
</ResponseField>

<ResponseField name="number_finished" type="number" required>
  Number of completed searches. Use this field to track progress.
</ResponseField>

<ResponseField name="status" type="string" required>
  Overall bulk search status: `ongoing`, `completed`, or `failed`.
</ResponseField>

<ResponseField name="results" type="array" required>
  List of individual results for each email.

  <Expandable title="Result properties">
    <ResponseField name="results[].id" type="string">
      Unique identifier for the individual search.
    </ResponseField>

    <ResponseField name="results[].email" type="string">
      The searched email.
    </ResponseField>

    <ResponseField name="results[].qualification" type="string">
      Status: `ongoing`, `found`, or `not_found`.
    </ResponseField>

    <ResponseField name="results[].linkedin_url" type="string">
      LinkedIn profile URL (if found).
    </ResponseField>

    <ResponseField name="results[].full_name" type="string">
      Full name (if found).
    </ResponseField>

    <ResponseField name="results[].headline" type="string">
      LinkedIn headline (if found).
    </ResponseField>

    <ResponseField name="results[].company_name" type="string">
      Current company (if found).
    </ResponseField>

    <ResponseField name="results[].location" type="string">
      Location (if found).
    </ResponseField>
  </Expandable>
</ResponseField>

## Polling for large volumes

For large bulk searches, implement polling with backoff:

```javascript theme={null}
async function waitForBulkCompletion(bulkId, apiKey) {
  let delay = 2000; // Start at 2 seconds
  const maxDelay = 30000; // Maximum 30 seconds

  while (true) {
    const response = await fetch(
      `https://api.reverselooker.com/reverse-contact/bulk?id=${bulkId}`,
      { headers: { 'x-api-key': apiKey } }
    );

    const data = await response.json();

    console.log(`Progress: ${data.number_finished}/${data.number_requested}`);

    if (data.status === 'completed' || data.status === 'failed') {
      return data;
    }

    await new Promise(resolve => setTimeout(resolve, delay));
    delay = Math.min(delay * 1.5, maxDelay); // Exponential backoff
  }
}
```

<Note>
  The bulk response contains a summary of profiles (name, headline, company, location). To get the full profile of a contact (experience, education, skills), use `GET /reverse-contact/single` with the individual ID.
</Note>

<Tip>
  Configure a **webhook** when creating the bulk search to be automatically notified when processing is complete.
</Tip>