Skip to main content
Access: All users. See Access control.

research_contacts

Research (enrich) contacts to get verified emails, phone numbers, job history, and other data. Each contact consumes credits for the components it researches (see researchTypes); credits for data that is not found are refunded, and the request is rejected with insufficient credits when the balance cannot cover every contact. Provide searchResultIds from a previous search_contacts call OR a contacts array. Set waitForResults: true to auto-poll up to 30s; otherwise returns requestIds to use with poll_contact_research. Researched contacts are saved and can be retrieved with get_my_contacts. Pass listIds to file every newly saved contact into those contact lists — use get_lists to find an existing list, or create_list first for a new one. Contacts that were already researched are not re-saved, so add those to a list with update_my_contact instead.

Arguments

string[]
Search result IDs from a previous contact search to research. Shares a budget of 500 items with the contacts array.Up to 500 items.
object[]
Contacts to enrich. Each must include one of: contactName+companyName, contactName+domain, email, liProfileUrl, liSalesNavUrl, or liRecruiterUrl. Shares a budget of 500 items with searchResultIds.Up to 500 items.
boolean
When true, research job changes. Use contacts array only (not searchResultIds).
(integer | string)[]
IDs of contact lists to add each newly saved contact to. Get IDs from get_lists, or create_list for a new list.Up to 50 items.
boolean
default:"false"
When true, bypasses the deduplication check so an already-researched contact is researched again as a new contact. Consumes credits each time.
string[] | null
Contact data to research for every contact: [“email”], [“phone”], or both. Omit to use the account’s Contact Data settings. Default prices in credits: email 1, phone 5, both 6. One component can be rejected with 403 (fullContactRequired, component-disabled-for-org, variable-credits-disabled); the error says how to recover. Asking for a component that a contact researched in the last few minutes lacks adds it to that contact and charges only that component.One of: email, phone.
boolean
default:"false"
When true, auto-polls up to 30s. Returns results if complete, or current state + requestIds if still pending. When false (default), returns requestIds immediately.

Result

Returns a text content block describing the outcome, plus a structuredContent object that mirrors it. This tool publishes no outputSchema, so the object’s fields are not guaranteed; treat every field as optional and nullable.

Credits

Research draws from the universal balance that get_credits and seamless://credits report. Each contact is charged for the contact data it researches, at the default prices researchTypes lists above (details). The organization may set its own prices, and accounts that aren’t on component-based pricing pay a flat price per contact (1 credit unless the organization has custom pricing).
  • researchTypes: ["email"], ["phone"], or ["email", "phone"], applied to every contact in the call. Without it, research covers what the account’s Contact Data settings enable.
  • Rejections (returned as a tool error before anything is charged): fullContactRequired when the organization is locked to Full Contact and one component was sent, component-disabled-for-org when the organization disabled a component that was sent, and variable-credits-disabled when the account isn’t on component-based pricing and one component was sent. An invalid researchTypes is rejected the same way. Recover by omitting researchTypes, sending both components, or removing the disabled one.
  • Insufficient credits: the call fails with an insufficient-credits error when the balance can’t cover every contact at its cost. That cost is an upper bound: a contact already in My Contacts, or a follow-up that identifies the same person differently, is only recognized once research runs and can cost less or nothing.
  • Refunds: with component-based pricing, email and phone are refunded separately when that data isn’t found (no valid business email, or no contact phone such as a mobile or main line; company phones are free). Phone is charged once per contact however many numbers are found. Organizations on a mobile-only agreement are only charged for mobile phones. Accounts that find full contacts only get the whole contact refunded when no valid email is found. Refunds land as each research completes, so read seamless://credits after polling finishes.
  • Repeat research: researching a contact again within a few minutes returns duplicate and charges nothing when the contact already has the requested contact data. Asking for a component it doesn’t have yet researches that component onto the same contact, charges only that component, and its researchedTypes becomes the union. skipDeduplicationCheck: true researches it again as a new contact.
  • Poll statuses: if the organization’s settings change between the call and the research, poll_contact_research reports fullContactRequired, component-disabled-for-org, or variable-credits-disabled as the result’s status. A done contact carries researchedTypes, so a missing component can be told apart from one that wasn’t found.

Example

poll_contact_research

Poll for contact research results. Pass requestIds from research_contacts. Returns each result with a status: done, error, missing, not found, or a researchTypes rejection (fullContactRequired, component-disabled-for-org, variable-credits-disabled). Poll again if any results are not in a terminal status. A done result carries the enriched contact, including jobHistory — the contact’s prior roles as companyName/title/startedAt/endedAt, most recent departure first, and an empty array when none are known.

Arguments

string[]
required
Request IDs returned from research_contacts to poll for results.Up to 500 items.

Result

Returns a text content block and a structuredContent object with these fields. Treat every field as nullable: a value the record does not have comes back as null.
object[]
required
Result records for the current page
object
Pagination metadata when available. Carries only the values the service has, so treat a missing key as unknown rather than zero; nextCursor is null or absent on the last page.

Example

research_companies

Research (enrich) companies to get verified details like revenue, size, and technologies. Consumes credits. Provide searchResultIds from a previous search OR a companies array. Set waitForResults: true to auto-poll up to 30s; otherwise returns requestIds to use with poll_company_research.

Arguments

string[]
Search result IDs from a previous company search to research. Shares a budget of 500 items with the companies array.Up to 500 items.
object[]
Companies to research. Each must include either domain or companyName. Shares a budget of 500 items with searchResultIds.Up to 500 items.
boolean
default:"false"
When true, bypasses the deduplication check so an already-researched record is enriched again. Consumes credits each time.
boolean
default:"false"
When true, auto-polls up to 30s. Returns results if complete, or current state + requestIds if still pending. When false (default), returns requestIds immediately.

Result

Returns a text content block describing the outcome, plus a structuredContent object that mirrors it. This tool publishes no outputSchema, so the object’s fields are not guaranteed; treat every field as optional and nullable.

Example

poll_company_research

Poll for company research results. Pass requestIds from research_companies. Returns each result with a status: done, error, or missing. Poll again if any results are not in a terminal status.

Arguments

string[]
required
Request IDs returned from research_companies to poll for results.Up to 500 items.

Result

Returns a text content block and a structuredContent object with these fields. Treat every field as nullable: a value the record does not have comes back as null.
object[]
required
Result records for the current page
object
Pagination metadata when available. Carries only the values the service has, so treat a missing key as unknown rather than zero; nextCursor is null or absent on the last page.

Example