Create Records Run
create_records_runCreate a run that searches a data provider for people matching your criteria and CREATES them in the CRM -- contacts that do not exist there yet, each attached to its employer's account. If a person's employer is already an account, the contact is attached to it; if not, the account is created first, so this never duplicates an account you already have. THIS IS THE ONLY TOOL THAT ADDS RECORDS. Every other tool changes records that already exist, so this one takes no filter -- there is nothing to filter over. IT SPENDS MONEY when dispatched: one provider credit per contact created (record_cap is how many you want), and credit_cap, at least record_cap, is the most the whole run may spend: people it finds who moved are looked up for job changes with what the creates leave, and any past it are reported as not looked up. Searching is free. CALL list_search_criteria FIRST, the way a filter follows list_filterable_fields: the search schema names the criteria but not that a department is 'Engineering & Technical' rather than 'Engineering'. A wrong value in one of the six with a fixed vocabulary is refused HERE, naming what it should have been -- industry, job_function, management_level, department, company_type and has. A wrong free-text value (job_title, company_name, state, country, postal_code) cannot be checked against a list and is only discovered by the provider at DISPATCH, after the run exists. An unlisted criterion is always refused here. template_id names an ENRICHMENT configuration, which says where each provider field lands in the CRM; list them with list_rule_templates. It must map something to LastName (lastname on a HubSpot connection) or the run is refused, because a contact needs a last name. A lead run takes a LEAD configuration, which must also map Company; HubSpot has no lead to create. WITH A CLAY CONFIGURATION (one whose Clay function returns people for each company), the run searches nobody: send search as [] and name companies instead, CRM accounts by a filter or companies not in the CRM by id, name and domain. Each company is one row of the tenant's own Clay function, which decides who to return (the persona lives there); credit_cap is how many companies may be sent and record_cap how many people may be created. A person found at a CRM account is created under it.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"connection_id": "<connection_id>",
"credit_cap": "<credit_cap>",
"name": "<name>",
"record_cap": "<record_cap>",
"search": "<search>",
"template_id": "<template_id>"
},
"name": "create_records_run"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | A name for the run, shown in the Runs tab. Dispatching this CREATES NEW RECORDS in the CRM and spends one provider credit for each. | |
| search | Yes | Who to bring in, as rows of input/operator/value. Every row must hold (they are ANDed); several values in one row mean ANY of them. Call list_search_criteria for each input's operators and its exact vocabulary — the values that read most plausibly are often the ones this provider refuses. person_ids is exclusive: it NAMES people, so it cannot share a search with rows that describe a population. Specific people, by provider id (is) — free text Job title (contains/is exactly/is not) — free text; “is exactly” wants the WHOLE title character for character (“Vice President, Global Sales Operations”), so it usually finds nobody — “contains” is almost always what you want. Job function (is) — one of 186 values Management level (is/is not) — one of 6 values Department (is) — one of 11 values Industry (is/is primarily) — one of 180 values Company name (is) — free text Company, by provider id (is) — free text Company type (is) — one of 3 values State or region (is) — free text Country (is) — free text Postal code (is) — free text Has (is) — one of 5 values; several values mean ALL of them, so this input NARROWS. “email” is worth reaching for: barely half of any population has a business email Employees (at least/at most) — a whole number Revenue (at least/at most) — a whole number Contact accuracy (at least) — a whole number; 70 to 99 | |
| companies | No | Only with a Clay configuration, and then required, with `search` empty: the companies to find people at, each sent to the configuration's Clay function, which returns the people. {"accounts": a filter over accounts} for CRM accounts (null for every account), or {"companies": [{"id", "name", "domain"}]} for companies not in the CRM. With Clay, credit_cap is how many companies may be sent, and record_cap how many people may be created. | |
| tam_check | No | Apply the connection's TAM to each person found before creating them: a person whose new contact, or whose employer account, would fall outside the TAM is not created and is reported with the criteria it failed. Their credit is already spent. Refused when the connection has no TAM. Subscription sets it, because its search is compiled from the TAM and can come back wider than it. | |
| credit_cap | Yes | Required: the most provider credits this run may spend in all, at least record_cap. Its creates spend first; people it finds who moved are looked up for job changes with what is left, and any past that are reported as not looked up. | |
| record_cap | Yes | Required: how many contacts to create. Each costs one Enrich credit; searching is free. | |
| update_cap | No | How many people the provider matches who are ALREADY contacts here may be refreshed with current data instead of skipped. 0 (the default) skips them and reports how many there were. Refreshing costs no credit; it bounds how long the run takes and how many records it writes. A plan that runs on a schedule must set it above 0, or every firing after the first finds the same people already known and does nothing for them. | |
| disposition | No | Who releases this run's writes. 'execute' dispatches the pass on request, which is the default. 'queue' stamps the run awaiting_approval and launches nothing until a person approves it, which for this tool also means no provider credit is spent. There is no 'propose' here: a create run brings in records that do not exist yet, so a per-record proposal would name no CRM record and link to nothing a reviewer could open. Reviewing a create is reviewing the run. | execute |
| object_type | No | Which CRM object the run targets. Contact and Lead only — an account is minted as a CONTACT's parent when its employer is not already one, and never as the subject of its own run. A LEAD has no parent: its employer is the Company field, which its LEAD configuration must fill, as it must fill LastName. | contact |
| template_id | Yes | Required: an enrichment configuration, by id (list_rule_templates), whose mapping decides which provider fields are written to each new contact. A field set to dont_update is not written. | |
| scope_filter | No | With tam_check, the filter to check each new person against instead of the connection's TAM: {"account": a filter group over companies or null, "persona": a filter group over people or null}. A prebuilt plan scoped by a filter sets it. | |
| connection_id | Yes | The CRM connection. Required. Call list_crm_connections to get one. | |
| create_accounts | No | Create the person's employer as a new account when it matches no existing account. Default true; false leaves such contacts without an account. |