Route a lead
/v1/routeNo “Try it” here: every call is real and consumes enrichment credits. Run the code samples from your own backend.
Routes a lead, identified by email, with one of your routing rules and returns the decision: the outcome, the matching segment, the assignee (the team member the rule routed the lead to), the accountOwner (the owner of the lead's account in your CRM, when that person is a Knock team member), and the enriched person and company.
The answer is synchronous and usually takes a few seconds: Knock waits up to about 6 seconds for the lead's enrichment so the rule can use it. If it is not ready by then, enrichment.status is pending and the rule is evaluated without it.
The email is added to the contacts in your Knock workspace, marked unverified, and enriching the lead uses credits from your Knock account. Both happen on a test call too.
Set test: true to test an integration: Knock runs the same rule and returns the same answer, but the lead isn't assigned (the rotation doesn't move), the routing result isn't saved and nothing is written to your CRM. With syncToCrm: false the decision is live, but this call does not write to your CRM.
Every live call is a new decision: there is no idempotency key, and the round-robin rotation moves on each call. Call once per lead event, such as a form submission.
Send Content-Type: application/json. Unknown fields are ignored.
ApiKeyAuthx-api-key<token>Your Knock API key. Ask your Knock account team for one: a key with the Enrichment API role for enrichment and routing, or the Viewer role for chats and meetings.
application/json- body
A lead to route.
routingId*stringThe ID of a routing rule from Workflow Routing in the Knock dashboard (Copy Routing Rule ID).
uuidemail*stringThe lead's email. At most 254 characters: a longer value is rejected as an invalid email.
emaillength <= 254syncToCrm?booleanSet to false so this call writes nothing to your CRM. The decision is still live: the lead is assigned and Knock saves the routing outcome. If the lead already exists in your CRM, a later update from Knock, for example when its enrichment completes, can still write the outcome there.
truetest?booleanRun the routing rule without acting on it: the lead isn't assigned (the rotation doesn't move), the routing result isn't saved and nothing is written to your CRM. The lead is still added to your contacts and enrichment still uses credits.
falseWhere the rule routed the lead.
application/json- response
Where a routing rule sent the lead.
decisionId*stringID of this decision. Every call returns a new one. Include it when you contact Knock about a decision.
uuidtest*booleantrue when this was a test call: nothing was assigned or written.
outcome*stringHow the rule routed the lead:
matched: A segment of the rule matched, and its outcome qualifies the lead.fallback: No segment matched, and the rule's fallback qualifies the lead.disqualified: A Disqualify segment matched, or no segment matched and the fallback disqualifies the lead.crm_owner: The rule's CRM-owner step assigned the lead to its existing owner in your CRM, before any segment was checked.
"matched""fallback""disqualified""crm_owner"segment*|nullThe segment that matched. Null when no segment matched: fallback, crm_owner, or disqualified by the fallback.
assignee*|nullThe team member the rule routed the lead to. Null when the rule assigned no one, for example when the lead is disqualified.
accountOwner*|nullThe owner of the lead's account in your CRM, when that person is a Knock team member. Null when the account has no owner, the owner is not a Knock team member, or Knock could not read your CRM at that moment.
enrichment*The enriched lead.
company*|nullThe lead's current company, the same as enrichment.person.company. Null when Knock has not resolved it.
curl -X POST 'https://app.knock-ai.com/v1/route' \ -H 'x-api-key: <YOUR_API_KEY>' \ -H 'Content-Type: application/json' \ -d '{ "routingId": "6c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "email": "jane@acme.com"}'{ "decisionId": "8e9f0a1b-2c3d-4e5f-8a7b-9c0d1e2f3a4b", "test": false, "outcome": "matched", "segment": { "id": "1f2e3d4c-5b6a-4978-8a6b-5c4d3e2f1a0b", "name": "Enterprise NA" }, "assignee": { "memberId": "5a7c9e1b-3d5f-4a6b-8c9d-0e1f2a3b4c5d", "email": "alex@yourcompany.com", "name": "Alex Kim" }, "accountOwner": { "memberId": "5a7c9e1b-3d5f-4a6b-8c9d-0e1f2a3b4c5d", "email": "alex@yourcompany.com", "name": "Alex Kim" }, "enrichment": { "status": "completed", "person": { "firstName": "Jane", "lastName": "Doe", "title": "VP Sales", "seniority": "VP", "profession": "Sales", "linkedinUrl": "https://www.linkedin.com/in/jane-doe", "location": "Austin, Texas, United States", "photoUrl": "https://media.example.com/jane-doe.jpg", "currentPositionStartDate": "2024-03", "company": { "name": "Acme", "domain": "acme.com", "logoUrl": "https://logo.example.com/acme.png", "description": "Acme builds scheduling software for revenue teams.", "industry": "COMPUTER_SOFTWARE", "size": "101-200", "employees": "120", "foundedDate": "2015", "totalFunding": "$22M", "lastFunding": "series_a", "annualRevenue": "$10m-$25m", "ownership": "Private", "headquarters": "New York, NY", "country": "US", "region": "North America", "state": "New York", "competitors": "Globex, Initech", "techStack": [ { "name": "Salesforce", "category": "CRM" } ], "teamSize": [ { "department": "Sales", "headcount": 40 } ], "fundingRounds": [ { "type": "series_a", "amountMillions": 22, "currency": "USD", "date": "2024-03-01", "investors": [ "Example Ventures" ] } ], "accountIntel": { "targetPersona": [ "Sales Director" ], "segments": [ "Enterprise", "SMBs" ], "verticals": [ "Software" ], "spaces": [ "Sales" ], "productTypes": [ "Inbound scheduling & routing" ], "salesMotions": [ "Sales-Led" ] }, "decisionMakers": [ { "name": "Bob Smith", "title": "CRO", "linkedinUrl": "https://www.linkedin.com/in/bob-smith", "matchedRole": "Sales leader" } ] } } }, "company": { "name": "Acme", "domain": "acme.com", "logoUrl": "https://logo.example.com/acme.png", "description": "Acme builds scheduling software for revenue teams.", "industry": "COMPUTER_SOFTWARE", "size": "101-200", "employees": "120", "foundedDate": "2015", "totalFunding": "$22M", "lastFunding": "series_a", "annualRevenue": "$10m-$25m", "ownership": "Private", "headquarters": "New York, NY", "country": "US", "region": "North America", "state": "New York", "competitors": "Globex, Initech", "techStack": [ { "name": "Salesforce", "category": "CRM" } ], "teamSize": [ { "department": "Sales", "headcount": 40 } ], "fundingRounds": [ { "type": "series_a", "amountMillions": 22, "currency": "USD", "date": "2024-03-01", "investors": [ "Example Ventures" ] } ], "accountIntel": { "targetPersona": [ "Sales Director" ], "segments": [ "Enterprise", "SMBs" ], "verticals": [ "Software" ], "spaces": [ "Sales" ], "productTypes": [ "Inbound scheduling & routing" ], "salesMotions": [ "Sales-Led" ] }, "decisionMakers": [ { "name": "Bob Smith", "title": "CRO", "linkedinUrl": "https://www.linkedin.com/in/bob-smith", "matchedRole": "Sales leader" } ] }}