Routing API

The Routing API runs one of your Knock routing rules for a single lead, from your own systems. You send an email and the ID of a routing rule, and Knock enriches the lead, walks the rule's segments and answers right away with the outcome: which segment matched, which team member gets the lead, who owns the account in your CRM, and the person and company Knock found.

You build the routing logic once, in the dashboard, with the same segments, filters and fallback you use for your forms. The API is how any other entry point (a custom form, a product sign-up, a chatbot, a marketing automation step) gets the same answer.

EndpointCopy Anchor Link

The call needs a key with the Enrichment API role (Admin keys work too). See Authentication.

Set up a routing ruleCopy Anchor Link

Route a leadCopy Anchor Link

POST https://app.knock-ai.com/v1/route

curl -X POST https://app.knock-ai.com/v1/route \
  -H "x-api-key: $KNOCK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routingId": "8b1f0c2e-4d6a-4c3e-9f1b-2a7d5e8c0f13",
    "email": "jane@acme.com"
  }'

ResponseCopy Anchor Link

{
  "decisionId": "c0a8e2b4-7f3d-4a1e-9b6c-5d2f8e1a7c90",
  "test": false,
  "outcome": "matched",
  "segment": { "id": "1f2e3d4c-5b6a-4978-8a6b-5c4d3e2f1a0b", "name": "Enterprise NA" },
  "assignee": { "memberId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "email": "dana@yourcompany.com", "name": "Dana Rep" },
  "accountOwner": null,
  "enrichment": {
    "status": "completed",
    "person": {
      "firstName": "Jane",
      "lastName": "Doe",
      "title": "VP Sales",
      "seniority": "VP",
      "profession": "Sales",
      "linkedinUrl": "https://www.linkedin.com/in/janedoe",
      "location": "Austin, Texas, United States",
      "photoUrl": null,
      "currentPositionStartDate": "2024-03",
      "company": { "name": "Acme", "domain": "acme.com", "size": "1001-5000", "industry": "COMPUTER_SOFTWARE", "…": "…" }
    }
  },
  "company": { "name": "Acme", "domain": "acme.com", "size": "1001-5000", "industry": "COMPUTER_SOFTWARE", "…": "…" }
}

Every key is always present, including the null ones.

OutcomesCopy Anchor Link

A segment filter on data Knock doesn't have for the lead (for example, company size before the company is found) doesn't match, so the walk moves on to the next segment.

TimingCopy Anchor Link

Knock answers synchronously, usually within a few seconds. It waits up to about 6 seconds for the lead's enrichment, so that segments filtering on title, seniority or company data can match. When enrichment isn't finished in time, Knock routes on what it has and enrichment.status is pending. When the person was already looked up without a match, Knock doesn't wait.

Set your HTTP client timeout to at least 30 seconds. Call the API from your backend after the lead submits, not in the critical path of rendering a page.

Test without side effectsCopy Anchor Link

Send "test": true to run the same rule and get the same answer without acting on it:

• the lead isn't assigned, and the segment's rotation doesn't move;
• the routing result isn't saved in Knock;
• nothing is written to your CRM.

The lead is still added to your Knock contacts and enrichment still uses credits, just like the Enrichment API. Use real work emails you control, or your own, to test each segment of the rule.

{
  "routingId": "8b1f0c2e-4d6a-4c3e-9f1b-2a7d5e8c0f13",
  "email": "jane@acme.com",
  "test": true
}

What a live call doesCopy Anchor Link

Without test, Knock acts on the decision:

• Assigns the lead. The routing result, with its assignee, is saved on the contact in Knock under the source Routing API, and the segment's rotation moves to its next rep.
• Writes to your CRM when syncToCrm is true (the default): Knock creates or updates the lead in your connected CRM and sets its owner, following your CRM settings in Knock.
• Adds the lead to your contacts and uses enrichment credits.

The Routing API never contacts the lead: Knock sends no LinkedIn or email outreach for API decisions. Your own system decides what happens next with the response.

Every live call is a new decision, and there is no idempotency key: calling twice for the same lead assigns it twice and moves the rotation twice. Call the API once per lead event, such as one form submission.

CRM syncCopy Anchor Link

With "syncToCrm": false, this call doesn't write to your CRM. Use it when your own system, or another tool, owns the CRM write: read assignee and segment from the response and write them yourself. The routing result is still saved in Knock.

ErrorsCopy Anchor Link

See Errors for the error format and the codes every endpoint shares.

Use casesCopy Anchor Link