Bulk Find Emails

Find email addresses for multiple contacts in a single request

POST /v1/find/bulk

Bulk Find Emails

cURL

curl --request POST \
  --url https://api.gtmapis.com/v1/find/bulk \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "contacts": [
    {}
  ],
  "validate": true,
  "max_concurrent": 123
}
'

200

{
  "id": "<string>",
  "results": [
    {}
  ],
  "summary": {}
}

Bulk Find Emails

Find professional email addresses for up to 100 contacts in a single request. Optimized for high throughput with concurrent processing.

Endpoint

POST /v1/find/bulk

Request

contacts · array · required

Array of contacts to find emails for (max 100)

validate · boolean · default: "false"

If true, automatically validate found emails. Charges additional credits for validation.

max_concurrent · integer · default: "5"

Maximum concurrent provider requests (1-10). Higher values are faster but may hit rate limits.

Contact Object

Each contact in the contacts array should include:

Field	Type	Required	Description
first_name	string	Yes	Person’s first name
last_name	string	Yes	Person’s last name
domain	string	No*	Company domain (e.g., “acme.com”)
company	string	No*	Company name
linkedin_url	string	No	LinkedIn profile URL

*Either domain or company is required for each contact.

Example Request

cURL

curl -X POST https://api.gtmapis.com/v1/find/bulk \
  -H "Content-Type: application/json" \
  -H "X-API-Key: gtm_test_your_key_here" \
  -d '{
    "contacts": [
      {
        "first_name": "John",
        "last_name": "Doe",
        "domain": "acme.com"
      },
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "company": "Widgets Inc",
        "linkedin_url": "https://linkedin.com/in/janesmith"
      }
    ],
    "max_concurrent": 5
  }'

Response

id · string

Unique identifier for this batch request

results · array

Array of results in the same order as the input contacts

summary · object

Aggregate statistics for the batch

Summary Object

Field	Type	Description
total	integer	Total contacts processed
found	integer	Emails successfully found
not_found	integer	Contacts where email not found
errors	integer	Contacts that failed with errors
credits_charged	integer	Total credits charged
total_latency_ms	integer	Total processing time

Example Response

{
  "id": "batch_550e8400-e29b-41d4-a716-446655440000",
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "email": "[e-mail]",
      "confidence": 95,
      "source_provider": "prospeo",
      "providers_tried": ["prospeo"],
      "pattern": "{first}.{last}",
      "not_found": false,
      "credits_charged": 1,
      "latency_ms": 342
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "email": "[e-mail]",
      "confidence": 85,
      "source_provider": "leadmagic",
      "providers_tried": ["prospeo", "leadmagic"],
      "pattern": "{first}",
      "not_found": false,
      "credits_charged": 1,
      "latency_ms": 856
    }
  ],
  "summary": {
    "total": 2,
    "found": 2,
    "not_found": 0,
    "errors": 0,
    "credits_charged": 2,
    "total_latency_ms": 1198
  }
}

Credit Pricing

Result	Credits Charged
Email found (confidence >= 70%)	1 credit per email
Email found (confidence < 70%)	0 credits
Email not found	0 credits
+ Auto-validation (if enabled)	Additional credits per valid email

Credits are charged per successful high-confidence result, not per contact submitted.

Limits

Limit	Value
Max contacts per request	100
Max concurrent requests	10
Rate limit	10,000 requests/minute

Performance Tips

Batch size recommendations

• 1-10 contacts: Single request works well
• 10-100 contacts: Use this bulk endpoint
• 100+ contacts: Split into multiple bulk requests

Concurrency tuning

• Start with max_concurrent: 5 (default)
• Increase to 10 for faster results (may hit provider limits)
• Decrease to 2-3 if seeing many errors

Provide domains over company names

Domains are more precise than company names. When you have both, prefer domain.

Related Endpoints

Find Single Email

Find email for a single contact

Finder History

View your email finder history