How do I pull contractor employee email information at scale?

The Shovels API provides a dedicated endpoint to retrieve employee information for specific contractors, including both personal and business email addresses, job titles, and seniority levels. This is particularly useful for identifying key decision-makers like owners, sales directors, and other personnel likely to respond to outreach efforts.

Using the List Contractor Employees Endpoint

The /contractors/{id}/employees endpoint returns comprehensive employee data for a specific contractor. Here's how to use it:

Endpoint: GET /contractors/{id}/employees

Authentication: Include your API key in the header as X-API-Key: YOUR_API_KEY_HERE

Required Parameters:

• {id} - The contractor ID (path parameter)

Optional Parameters:

• cursor - For pagination through large result sets
• page - Page number for offset-based pagination
• size - Number of items per page (1-100)

Sample Request

curl --request GET \
  --url https://api.shovels.ai/v2/contractors/{id}/employees \
  --header 'X-API-Key: YOUR_API_KEY_HERE'

Response Data

The API returns employee records containing:

Contact Information:

• email - Personal email address
• business_email - Business email address
• phone - Phone number
• linkedin_url - LinkedIn profile

Professional Details:

• job_title - Current position
• seniority_level - Senior, Mid, Junior, etc.
• department - Department or division

Additional Data:

• name - Full name
• Address details (street, city, state, zip)
• Demographics (age range, income range, etc.)

Scaling Your Data Collection

Pagination: The endpoint supports cursor-based pagination for handling large employee lists. Use the next_cursor value from the response to retrieve subsequent pages.

Bulk Processing: To process multiple contractors at scale:

1. First, obtain contractor IDs using the contractors search endpoints
2. Iterate through each contractor ID
3. Call the employees endpoint for each contractor
4. Implement proper error handling and rate limiting

Targeting Decision Makers: Filter results by seniority_level (Senior, Executive) and job_title to identify owners, sales directors, and other key personnel most likely to respond to outreach.

Best Practices

• Respect rate limits and avoid frivolous requests
• Use pagination to handle large datasets efficiently
• Store and cache results to minimize API calls
• Filter by job titles and seniority levels to focus on decision-makers
• Always include proper error handling in your implementation

Getting Started

To begin using this endpoint, you'll need a Shovels API key available in your Profile Settings. The API includes a free trial with 250 requests to help you test the functionality before committing to a paid plan.