Import prospects

Pull people from the prospect database into Contacts, revealed on the way in. By ids, or by filters plus a limit of up to 3,000. Only people a vendor returned an address for become contacts. Spends data credits per reveal. A large pull can run for minutes; send an Idempotency-Key so a timed-out request is never paid for twice.

POSThttps://app.trygtm.com/api/v1/prospects/import

Scope: write
Cost: 8 data credits per unit — enrich.reveal
MCP tool: import_prospects

Headers

Idempotency-Keystringoptional: A key unique to this write, up to 255 characters. A retry carrying the same key returns the first response instead of running again. Kept for 24 hours.

Body

idsstring[]optional: Prospect ids from search_prospects. Omit to import by filter instead.
limitnumberoptional: With filters and no ids: how many matching people to pull, newest page first. Up to 3000. Pass the count when the person asked for everyone.
list_namestringoptional: A static list the pull lands on, created if it does not exist. Name it after the ICP, e.g. 'Life insurance agents — Florida'.
list_idstring | nulloptional: An existing static list to land the pull on, from list_lists. Takes precedence over listName. Use null when absent; never invent an id.
saved_search_idstringoptional: A saved search's id from list_saved_searches. Runs that search's own filters and corpus, exactly as the Search screen does. Use it instead of search when the operator names a saved search; never pass a saved search's name as search.
searchstringoptional: The Search screen's own filter model, as the compact JSON string list_saved_searches returns and save_search takes: {"job_info":{"job_title":{"include":[{"value":"<id>","label":"VP Sales"}]}},"company_employee_count":["3"]}. Lookup ids come from resolve_prospect_filter in the corpus the model searches (the whole database unless it uses sic_codes or an advanced axis). When given it replaces filters, freshOnly, enrichedOnly, liOnly and contactInfo, and the corpus follows from it. Every tool that takes it must be passed the same string.
filtersobjectoptional: Filter groups, each an object of field -> array of numeric ids from resolve_prospect_filter. job_info: job_title, seniority_level, department. company_info: company_industry, sic_codes, company_employee_count, company_revenue, company_name. company_location: company_country, company_state, company_city. location: country, state, city, personal_zip. advanced: social_connections, homeowner, net_worth, income_range, children, married, age_range. company_employee_count, company_revenue and the advanced fields are fixed bands, not lookups: resolve_prospect_filter answers them from their options (a range such as 18-25 returns every band it overlaps) and list_prospect_filters lists them. sic_codes, personal_zip and the advanced fields exist only with freshOnly: true and are refused otherwise, so a query using one resolves every other filter with freshOnly: true as well. In that corpus a person's city is rarely filled in: narrow a metro there with personal_zip, whose ids are the 5-digit ZIPs themselves (pass the metro's ZIPs together), or with state. Without a fresh-only axis, prefer freshOnly: false for a city, which resolves cities well. Job titles are exact labels: resolve the job and pass every returned label that is the same job (Life Insurance Agent, Licensed Life Insurance Agent, Independent Life Insurance Agent) as one ORed list. company_industry is a coarse list of about 150 labels per corpus; trades and local services (plumbing, roofing, HVAC, electrical, landscaping) are not on it. For those use sic_codes with freshOnly: true: the id is the 4-digit code itself (1711 plumbing, heating and air-conditioning contractors; 1761 roofing, siding and sheet metal; 1731 electrical work), the lookup's list is partial and reports no counts, so pass a code you know and size it with count_prospects. E.g. {job_info:{seniority_level:[3]}, location:{state:[44]}}. Narrow step by step: add one axis, count, then add the next. Flat keys are accepted too.
fresh_onlybooleanoptional: Defaults true. Selects which corpus — and therefore which id vocabulary — applies: every lookup, count, search and import for one market uses the same value. freshOnly: true is required by sic_codes, personal_zip and the advanced bands (age, income, homeowner…); there, narrow a place by state or personal_zip, because few people in that corpus have a city. freshOnly: false is the whole database and resolves cities well. When switching, re-resolve every filter in the other corpus. The fresh corpus holds United States people only; a workspace that sells elsewhere searches with freshOnly: false.
enriched_onlybooleanoptional: Defaults false. Only people the corpus already holds contact details for. Cheaper to reveal, smaller pool.
li_onlybooleanoptional: Defaults false. Only people with a LinkedIn profile URL, which every LinkedIn step needs.
contact_infostring[]optional: Require that a profile already holds these details, e.g. ["phone"] for an SMS audience. Narrows to people a reveal can answer for.emailwork_emailphone

Request

curl -X POST https://app.trygtm.com/api/v1/prospects/import \
  -H "Authorization: Bearer $TRYGTM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "5x5-91824417"
    ],
    "limit": 25
  }'

Response

{
  "data": {
    "filters_applied": "VP Demand Generation · Texas",
    "candidates": 100,
    "imported": 63,
    "enriched_with_address": 63,
    "unreachable": 31,
    "already_present": 4,
    "suppressed": 2,
    "credits_charged": 1890,
    "list": {
      "id": "5e6f7a8b-1c2d-4e3f-9a0b-1c2d3e4f5a6b",
      "name": "Logistics VPs — US"
    },
    "note": "Everyone imported carries a revealed address. People no vendor held an address for were not imported."
  }
}