Contact

For example, if someone from Bergquell Mineralbrunnen reads your pricing page several times, /contacts/search finds their head of marketing. Contacts originate from the contact search, not from tracking.

RulesCopy Anchor Link

These rules apply to every contact:

• Visiting companies only: The company_id must belong to a company that visited one of your websites. Otherwise search, lookup, and find answer with COMPANY_NOT_IDENTIFIED. The API doesn't search by domain, name, or person.
• Setup first: You set up contacts for your account once in the dashboard, and until then search, reveal, and find answer with CONTACTS_SETUP_REQUIRED. For details, see Set up contacts.
• Credits: Search and lookup cost no credits. reveal and find cost credits, but only for the data Webmetic delivers. For details, see Credits in the API.
• One account, one pool: Unlocked data belongs to your account, so all users, the dashboard, the API, and the AI assistant see it at no extra cost. Another Webmetic account doesn't see it.
• Free plan: For companies hidden on the Free plan, search, lookup, and find answer with PLAN_REQUIRED. For details, see Plans.
• Access: If your partner turned off the Data profiles feature, the API answers with FEATURE_DISABLED.

All error codes are listed under Errors.

FieldsCopy Anchor Link

This is how /contacts/search and /contacts/lookup return a contact in the contacts list:

The contact doesn't include the person's department, level, or location, even if you filter by department or level.

Fields until unlockedCopy Anchor Link

Four fields stay empty until your account unlocks the data:

• Email: Unlocking fills email and linkedin.
• Phone: Unlocking fills direct_phone and mobile_phone.

The search always returns these four fields as null, even for people your account has already unlocked. /contacts/lookup includes unlocked data and leaves out empty fields entirely. If your account hasn't searched this company with these filters yet, the lookup answers with exactly {"exists": false}.

Contact in reveal and findCopy Anchor Link

After unlocking, the contact has a different shape:

search, reveal, and find also return credits_used, the credits of this call, and credits_remaining, the credits your account has afterwards.

Country of the resultsCopy Anchor Link

Webmetic searches for people in the company's country. country names that country as an ISO code with two capital letters, for example DE.

If the search finds nobody there, Webmetic searches worldwide and sets country_fallback to true. If no country is known, country is null and the search also runs worldwide.

Both fields sit in the response of search, lookup, and find, not in the single contact. The lookup leaves out country when it's null.

PagesCopy Anchor Link

The pages of /contacts/search start at 0. A page holds 10 to 25 people, with 25 as the default. total counts all matching people, not only the ones on this page. In the lookup the field is called total_results, and the lookup returns only the first page. For details, see Pagination.

ExampleCopy Anchor Link

The example shows a search at Bergquell Mineralbrunnen before unlocking:

{
  "total": 14,
  "page": 0,
  "contacts": [
    {
      "contact_id": "v1.q7Rk2mXv9TnL4w",
      "name": "Miriam Eckhardt",
      "job_title": "Leiterin Marketing",
      "company_name": "Bergquell Mineralbrunnen GmbH",
      "has_email": true,
      "has_phone": true,
      "has_social_link": true,
      "email": null,
      "linkedin": null,
      "direct_phone": null,
      "mobile_phone": null
    }
  ],
  "from_cache": false,
  "country": "DE",
  "country_fallback": false
}

The response is shortened: credits_used and credits_remaining are left out. from_cache: true means the result comes from a stored search.

Edge casesCopy Anchor Link

• 404 when unlocking: If the person isn't from a search of your account or can no longer be found, /contacts/reveal answers with CONTACT_NOT_FOUND. Search again and use the contact_id from the new result.
• Data that can't be given out: For some people, Webmetic may not give out contact details. The API then answers with 404 and deducts no credits.
• Unlocking again: /contacts/reveal returns data your account has already unlocked again, at no cost.
• Empty despite has_email: If Webmetic finds no address when unlocking, email stays null. That data type then costs nothing and stays open.
• Company without a website: If no website is on file for the company, search, lookup, and find answer with 404 and COMPANY_WITHOUT_WEBSITE. The API returns no contacts for this company.
• No match in find: If nobody fits, /contacts/find answers with found: false and deducts nothing.

Used byCopy Anchor Link

• Endpoints: POST /contacts/search to search, GET /contacts/lookup for stored searches with unlocked data, POST /contacts/reveal to unlock, and POST /contacts/find to find and unlock in one call
• AI assistant: The AI assistant also finds and unlocks contacts, with the tools find_contacts and reveal_contact.