Skip to main content

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.

ParameterTypeDescription
industrystringFilter by industry — parent or sub-industry. Multiple industries can be combined. Values: Filter Values → industry (e.g., Technology)
job_titlestringFilter by job title (e.g., Software Engineer)
job_levelstringFilter by job level. Allowed values: Filter Values → job_level (e.g., C Level)
company_namestringFilter by company name
company_websitestringFilter 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_urlstringFilter 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_countrystringFilter by country (e.g., United States)
employee_rangestringFilter by employee count range. Allowed values: Filter Values → employee_range (e.g., 1,001-5,000)
revenue_rangestringFilter by revenue range. Allowed values: Filter Values → revenue_range (e.g., $ 100M - <250M)
keywordsstringFree-text search. Matched only against the fields named in keyword_fields.
keyword_fieldsstringComma-separated list of fields the keywords term is matched against (e.g., job_title,company_about_us). Only populated text fields are searched.
exclude_suppressionbooleanWhen true, contacts on your suppression lists are excluded from results.
limitintegerResults per page. Default: 10
offsetintegerPagination 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_website is an exact match on the stored domain, so send acme.com, not https://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 Level returns C-level contacts at Acme only.
  • URL-encode the value when it contains : or / (as in the --data-urlencode example).

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​

FieldTypeDescription
successbooleanAlways true on 200 OK
countintegerTotal records matching the filters (across all pages)
resultsarrayPage slice — up to limit records
results[].uuidstringRecord's UUID. Pass this to Unlock Records to reveal PII
results[].company_websitestring | nullThe company's domain (e.g., acme.com)
results[].company_linkedin_urlstring | nullThe company's LinkedIn page
results[].contact_emailstring | nullnull until you unlock email for this record
results[].contact_direct_phonestring | nullnull until you unlock phone for this record
results[].contact_mobile_phonestring | nullnull until you unlock phone for this record
results[].is_email_unlockedbooleantrue if this account has already unlocked email for this record
results[].is_phone_unlockedbooleantrue 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​

HTTPWhenBody
401Missing or invalid token{"detail": "Invalid token."}
400Invalid parameter (e.g., non-integer limit){"error": "..."}

See Error Codes for the full list.