# Lead routing

> Read and change your lead routes, try a lead, route the waiting leads and mark people away through the Fondaro API.

These routes let an API key read and change how new leads are routed. Routes are checked top to bottom and the first one that takes the lead and has someone who can get it wins; a route that ends with nobody falls through to the next, then to Smart routing, then to Unassigned. The concepts, the fields of a route and its conditions are in [Lead routing](https://www.fondaro.com/docs/api/lead-routing.md); this page lists the `/v1` routes.

Reading needs `crm:read`; changing needs `crm:write`. Everything here is for organization admins and needs an active plan, except **Mark a person away**, which any key with `crm:write` and an active plan may use for its own person. A member's key gets `403` on the admin routes. Writes accept an `Idempotency-Key` header where noted.

Lead routing is also available to AI clients through [Fondaro MCP](https://www.fondaro.com/docs/api/mcp.md), with the same rules.

## Get lead routing

`GET /v1/lead-routing`

The routes in order, who gets each route's leads and how, Smart routing on or off, the problems found, who is away, and how many leads each route took.

| Parameter | In | Type | Required | Description |
|-----------|----|------|----------|-------------|
| `days` | Query | integer | No | 1 to 90. How many days the per-route counts cover. Default 30 |

```bash
curl https://api.fondaro.com/v1/lead-routing \
  -H "Authorization: Bearer $FONDARO_API_KEY"
```

```json
{
  "routes": [
    {
      "id": "7f3c2a10-0000-4000-8000-000000000001",
      "name": "Idealista sellers",
      "summary": "came from Idealista and is a seller",
      "conditions": { "type": "group", "combinator": "and", "children": [] },
      "strategy": "round_robin",
      "position": 0,
      "paused": false,
      "members": [
        { "userId": "user_2abcDEF1234567890ghiJKL", "teamId": null, "name": "Ana Torres", "weight": 0 }
      ],
      "schedule": null,
      "dailyCap": 8,
      "reassignAfterMinutes": 30,
      "leadsLast30Days": 41
    }
  ],
  "smartRouting": {
    "enabled": true,
    "team": [{ "userId": "user_2abcDEF1234567890ghiJKL", "name": "Ana Torres" }]
  },
  "problems": [],
  "away": [{ "userId": "user_2defMNO1234567890pqrSTU", "until": "2026-10-20T00:00:00.000Z" }]
}
```

`position` is 0 for the route checked first. `summary` is the route's conditions in plain words. Each problem is `{ ruleId, code, sentence }`; the codes are listed in [Lead routing](https://www.fondaro.com/docs/api/lead-routing.md#problems).

## Try a lead

`POST /v1/lead-routing/preview`

Which route would take a lead, who would get it and why, without assigning anything. Needs `crm:read`.

| Parameter | In | Type | Required | Description |
|-----------|----|------|----------|-------------|
| `leadId` | Body | integer | No | An existing lead |
| `facts` | Body | object | No | A described lead: `source`, `origin`, `leadType`, `language` (BCP 47), `country` (two letters), `tagIds`, `growthAreaId`, `hasPhone`, `hasEmail`, `arrivedAt`. With `leadId` they override the lead's own |

```bash
curl -X POST https://api.fondaro.com/v1/lead-routing/preview \
  -H "Authorization: Bearer $FONDARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "facts": { "origin": "portal:idealista", "leadType": "seller", "language": "es-ES" } }'
```

```json
{
  "ruleId": "7f3c2a10-0000-4000-8000-000000000001",
  "routeName": "Idealista sellers",
  "smartRouting": false,
  "userId": "user_2abcDEF1234567890ghiJKL",
  "userName": "Ana Torres",
  "why": "Next in turn",
  "steps": [
    {
      "ruleId": "7f3c2a10-0000-4000-8000-000000000001",
      "outcome": "assigned",
      "skipped": [{ "userId": "user_2defMNO1234567890pqrSTU", "reason": "away" }]
    }
  ]
}
```

## Add a route

`POST /v1/lead-routing/rules`

Adds a route and returns it. Needs `crm:write`. Accepts an `Idempotency-Key` header.

| Parameter | In | Type | Required | Description |
|-----------|----|------|----------|-------------|
| `name` | Body | string or null | No | Up to 80 characters |
| `conditions` | Body | object or null | No | An AND/OR group of conditions. Null takes every lead |
| `strategy` | Body | string | No | `round_robin` (default), `weighted` or `smart` |
| `userIds` | Body | string or array | No | The people who get the leads |
| `teamIds` | Body | string or array | No | Teams read live when a lead arrives |
| `weights` | Body | object | No | `weighted` only: percent per user id, adding up to 100 |
| `paused` | Body | boolean | No | A paused route is skipped |
| `schedule` | Body | object or null | No | Office hours: `{ zone, days: [{ day, from, to }] }`, `day` 1 (Monday) to 7 |
| `dailyCap` | Body | integer or null | No | 1 to 1000. Most leads one person gets a day from this route |
| `reassignAfterMinutes` | Body | integer or null | No | 5 to 10080. Hand the lead on when nobody touched it in this long |
| `position` | Body | integer | No | Where in the order, 0 is first. Default: last, just above Smart routing |

```bash
curl -X POST https://api.fondaro.com/v1/lead-routing/rules \
  -H "Authorization: Bearer $FONDARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Idealista sellers",
    "conditions": {
      "type": "group", "combinator": "and",
      "children": [
        { "type": "condition", "field": "origin", "operator": "has_any_of",
          "value": { "kind": "strings", "values": ["portal:idealista"] } },
        { "type": "condition", "field": "leadType", "operator": "has_any_of",
          "value": { "kind": "strings", "values": ["seller"] } }
      ]
    },
    "userIds": ["user_2abcDEF1234567890ghiJKL"],
    "dailyCap": 8,
    "position": 0
  }'
```

The response is the route, in the shape shown under **Get lead routing**.

## Change a route

`PATCH /v1/lead-routing/rules/{ruleId}`

Takes any of the fields above. Fields you leave out stay as they are; sending `userIds` or `teamIds` replaces the pool. Returns the route. Needs `crm:write`.

```bash
curl -X PATCH https://api.fondaro.com/v1/lead-routing/rules/7f3c2a10-0000-4000-8000-000000000001 \
  -H "Authorization: Bearer $FONDARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "paused": true }'
```

## Delete a route

`DELETE /v1/lead-routing/rules/{ruleId}`

Leads the route would have taken go to the next route. Needs `crm:write`.

```bash
curl -X DELETE https://api.fondaro.com/v1/lead-routing/rules/7f3c2a10-0000-4000-8000-000000000001 \
  -H "Authorization: Bearer $FONDARO_API_KEY"
```

```json
{ "deleted": true, "ruleId": "7f3c2a10-0000-4000-8000-000000000001" }
```

## Reorder the routes

`PUT /v1/lead-routing/rules/order`

Give every route id in the new order, first is checked first. Smart routing always stays last and is not listed. Returns `{ "routes": [...] }`. Needs `crm:write`.

```bash
curl -X PUT https://api.fondaro.com/v1/lead-routing/rules/order \
  -H "Authorization: Bearer $FONDARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ruleIds": ["9a1c2b30-0000-4000-8000-000000000002", "7f3c2a10-0000-4000-8000-000000000001"] }'
```

## Switch Smart routing on or off

`PUT /v1/lead-routing/smart`

On, leads no route takes go to your whole team; off, they wait in Unassigned. Needs `crm:write`.

```bash
curl -X PUT https://api.fondaro.com/v1/lead-routing/smart \
  -H "Authorization: Bearer $FONDARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'
```

```json
{ "enabled": false }
```

## Route the waiting leads

`POST /v1/lead-routing/route-unassigned`

Sends the leads waiting in Unassigned through your routes now: up to 500, oldest first. A lead someone assigns meanwhile is left alone. Takes no body. Needs `crm:write`.

```bash
curl -X POST https://api.fondaro.com/v1/lead-routing/route-unassigned \
  -H "Authorization: Bearer $FONDARO_API_KEY"
```

```json
{ "considered": 37, "assigned": 31, "leftWaiting": 6 }
```

## Mark a person away

`PUT /v1/lead-routing/away`

Routing skips the person until the date. An admin may set anyone; anyone else may set only themself (leave `userId` out). Needs `crm:write`.

| Parameter | In | Type | Required | Description |
|-----------|----|------|----------|-------------|
| `userId` | Body | string | No | Whose away date. Default: the key's person |
| `until` | Body | string or null | Yes | ISO date or time they are back. `null` means back now |

```bash
curl -X PUT https://api.fondaro.com/v1/lead-routing/away \
  -H "Authorization: Bearer $FONDARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "userId": "user_2defMNO1234567890pqrSTU", "until": "2026-10-20" }'
```

```json
{ "userId": "user_2defMNO1234567890pqrSTU", "until": "2026-10-20T00:00:00.000Z" }
```

Source: https://www.fondaro.com/docs/api/v1/lead-routing