Search Records
Search the eCore DataCore database with filters. The endpoint returns matching person records with their company and job information. Personally Identifiable Information (PII) fields — email, direct phone, mobile phone — are hidden until you unlock them with Unlock Records.
Endpoint
Method: GET
Path: /external/search/
Full URL: https://backend.ecoreservice.com/api/v1/external/search/
Auth: Authorization: Token YOUR_API_TOKEN — see Authentication
Cost: Free — search itself never charges credits
Query Parameters
All parameters are optional. Provide one or more to filter. With no filters, results are returned newest-first.
| Parameter | Type | Description |
|---|---|---|
industry | string | Filter by industry — parent or sub-industry. Multiple industries can be combined. Values: Filter Values → industry (e.g., Technology) |
job_title | string | Filter by job title (e.g., Software Engineer) |
job_level | string | Filter by job level. Allowed values: Filter Values → job_level (e.g., C Level) |
company_name | string | Filter by company name |
company_website | string | Filter by company domain (e.g., acme.com). Pass the bare domain — no https://, www. or path. Comma-separate to match any of several companies (e.g., acme.com,globex.com). |
company_linkedin_url | string | Filter by the company's LinkedIn page (e.g., https://www.linkedin.com/company/acme). http/https, www. and a trailing slash are all matched. Comma-separate to match any of several companies. |
contact_office_country | string | Filter by country (e.g., United States) |
employee_range | string | Filter by employee count range. Allowed values: Filter Values → employee_range (e.g., 1,001-5,000) |
revenue_range | string | Filter by revenue range. Allowed values: Filter Values → revenue_range (e.g., $ 100M - <250M) |
keywords | string | Free-text search. Matched only against the fields named in keyword_fields. |
keyword_fields | string | Comma-separated list of fields the keywords term is matched against (e.g., job_title,company_about_us). Only populated text fields are searched. |
exclude_suppression | boolean | When true, contacts on your suppression lists are excluded from results. |
limit | integer | Results per page. Default: 10 |
offset | integer | Pagination offset. Default: 0 |
Example Request
curl -X GET \
"https://backend.ecoreservice.com/api/v1/external/search/?industry=Technology&job_level=C%20Level&limit=5" \
-H "Authorization: Token YOUR_API_TOKEN"
Search by Company Domain or LinkedIn URL
To pull contacts at specific companies, filter by company_website (the company's domain) or company_linkedin_url. These identify a company more reliably than company_name, which can be spelled many ways.
# Contacts at two companies, by domain
curl -X GET \
"https://backend.ecoreservice.com/api/v1/external/search/?company_website=acme.com,globex.com&job_level=C%20Level&limit=25" \
-H "Authorization: Token YOUR_API_TOKEN"
# Contacts at one company, by its LinkedIn page
curl -G "https://backend.ecoreservice.com/api/v1/external/search/" \
--data-urlencode "company_linkedin_url=https://www.linkedin.com/company/acme" \
-H "Authorization: Token YOUR_API_TOKEN"
company_websiteis an exact match on the stored domain, so sendacme.com, nothttps://www.acme.com/.- Several values in one parameter are combined with OR. Different parameters are combined with AND:
company_website=acme.com&job_level=C Levelreturns C-level contacts at Acme only. - URL-encode the value when it contains
:or/(as in the--data-urlencodeexample).
Keyword Search
Use keywords together with keyword_fields for free-text matching. keyword_fields is required alongside keywords — the term is matched only against the listed fields, and only where those fields are populated:
curl -X GET \
"https://backend.ecoreservice.com/api/v1/external/search/?industry=Software&keywords=devops&keyword_fields=job_title,company_about_us&limit=25" \
-H "Authorization: Token YOUR_API_TOKEN"
Suppression
If you maintain suppression lists, pass exclude_suppression=true to drop suppressed contacts from the results:
curl -X GET \
"https://backend.ecoreservice.com/api/v1/external/search/?industry=Software&exclude_suppression=true" \
-H "Authorization: Token YOUR_API_TOKEN"
Suppression also applies to Unlock Records (suppressed contacts are skipped and not charged) and to the Pipeline flow.
Successful Response — 200 OK
{
"success": true,
"count": 1250,
"results": [
{
"uuid": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
"first_name": "John",
"last_name": "Doe",
"company_name": "Acme Corp",
"company_website": "acme.com",
"company_linkedin_url": "https://www.linkedin.com/company/acme",
"job_title": "CEO",
"job_level": "C Level",
"industry": "Technology",
"contact_linkedin_url": "https://linkedin.com/in/johndoe",
"contact_email": null,
"contact_direct_phone": null,
"contact_mobile_phone": null,
"is_email_unlocked": false,
"is_phone_unlocked": false
}
]
}
Response Fields
| Field | Type | Description |
|---|---|---|
success | boolean | Always true on 200 OK |
count | integer | Total records matching the filters (across all pages) |
results | array | Page slice — up to limit records |
results[].uuid | string | Record's UUID. Pass this to Unlock Records to reveal PII |
results[].company_website | string | null | The company's domain (e.g., acme.com) |
results[].company_linkedin_url | string | null | The company's LinkedIn page |
results[].contact_email | string | null | null until you unlock email for this record |
results[].contact_direct_phone | string | null | null until you unlock phone for this record |
results[].contact_mobile_phone | string | null | null until you unlock phone for this record |
results[].is_email_unlocked | boolean | true if this account has already unlocked email for this record |
results[].is_phone_unlocked | boolean | true if this account has already unlocked phone for this record |
Pagination
Use limit and offset to walk through results:
# Page 1 — records 0-9
curl ".../external/search/?industry=Technology&limit=10&offset=0" -H "Authorization: Token ..."
# Page 2 — records 10-19
curl ".../external/search/?industry=Technology&limit=10&offset=10" -H "Authorization: Token ..."
The count field gives you the total result size to know when you've reached the end.
Error Responses
| HTTP | When | Body |
|---|---|---|
| 401 | Missing or invalid token | {"detail": "Invalid token."} |
| 400 | Invalid parameter (e.g., non-integer limit) | {"error": "..."} |
See Error Codes for the full list.