> ## Documentation Index
> Fetch the complete documentation index at: https://docs.routera.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Dispatch router

> POST /dispatch/router — assign an object using router rules

## Endpoint

```http theme={null}
POST https://api.routera.io/dispatch/router
```

**Route:** `/dispatch/router`\
**Authentication:** Bearer JWT

Runs router assignment logic for a given object: evaluates triggers, availability, distribution model, and assigns an owner when rules match.

## Request body

| Field       | Required | Description       |
| ----------- | -------- | ----------------- |
| `router_id` | Yes      | Router to execute |
| `object_id` | Yes      | Object to assign  |

```json theme={null}
{
  "router_id": "router-uuid",
  "object_id": "object-uuid"
}
```

## Responses

**200 — Assignment succeeded**

| Field               | Description                             |
| ------------------- | --------------------------------------- |
| `message`           | Human-readable outcome                  |
| `success`           | `true` when the object was assigned     |
| `user`              | Email of the assigned owner             |
| `field_name`        | Display name of the owner field updated |
| `owner_assigned_at` | Assignment timestamp (RFC 2822 UTC)     |

```json theme={null}
{
  "message": "The object was successfully assigned",
  "success": true,
  "user": "jane@example.com",
  "field_name": "contact_owner",
  "owner_assigned_at": "Thu, 12 Jun 2025 14:30:00 GMT"
}
```

When the router has a HubSpot integration and sync fails after a successful Routera assignment, the response is still **200** with `success: true` plus:

| Field                 | Description               |
| --------------------- | ------------------------- |
| `hubspot_sync_failed` | `true`                    |
| `hubspot_error`       | HubSpot sync error detail |

**200 — Other outcomes** (no assignment; response has `message` only, no `error` flag)

| `message`                                                      |
| -------------------------------------------------------------- |
| `Trigger did not match`                                        |
| `Router not found`                                             |
| `Object not found`                                             |
| `The router is unpublished`                                    |
| `The router has no settings`                                   |
| `Account not found`                                            |
| `Account is not active`                                        |
| `Assignment limit reached`                                     |
| `The router can not overwrite`                                 |
| `There are no users available and the backup user is disabled` |

**400** — Invalid JSON or missing required fields

```json theme={null}
{
  "message": "Invalid event: require router_id and object_id",
  "error": true
}
```

**500** — Processing error

```json theme={null}
{
  "message": "<error detail>",
  "error": true
}
```

<Note>
  This endpoint can also be invoked asynchronously via SQS with the same `router_id` and `object_id` fields in the message body.
</Note>


## OpenAPI

````yaml POST /dispatch/router
openapi: 3.0.1
info:
  title: Routera API
  description: >-
    Routera v2 REST API. Objects CRUD for contacts, companies, deals, and
    tickets, routers read API, plus router dispatch.
  version: 1.0.0
servers:
  - url: https://api.routera.io
    description: >-
      API Gateway base URL (override with ROUTERA_API_BASE_URL when generating
      docs)
security: []
tags:
  - name: Authentication
    description: Access token issuance
  - name: Contacts
    description: Contact records
  - name: Companies
    description: Company records
  - name: Deals
    description: Deal records
  - name: Tickets
    description: Ticket records
  - name: Routers
    description: Router configuration
  - name: Dispatch
    description: Router assignment
paths:
  /dispatch/router:
    post:
      tags:
        - Dispatch
      summary: Dispatch object to router
      description: >-
        Runs router assignment for an object. Requires router_id and object_id
        in the JSON body.
      operationId: dispatchRouter
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DispatchRequest'
      responses:
        '200':
          description: Dispatch completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DispatchResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
        - bearerAuth: []
components:
  schemas:
    DispatchRequest:
      type: object
      required:
        - router_id
        - object_id
      properties:
        router_id:
          type: string
          description: Router to run
        object_id:
          type: string
          description: Object to assign
    DispatchResponse:
      type: object
      description: >-
        Assignment succeeded, or a non-error outcome (HTTP 200). When `success`
        is true, the object was assigned.
      properties:
        message:
          type: string
        success:
          type: boolean
          description: Present and true when the object was assigned
        user:
          type: string
          description: Email of the user assigned as owner
        field_name:
          type: string
          description: Display name of the owner field that was updated
        owner_assigned_at:
          type: string
          description: Assignment timestamp (RFC 2822 UTC)
        hubspot_sync_failed:
          type: boolean
          description: True when Routera assigned the owner but HubSpot sync failed
        hubspot_error:
          type: string
          description: HubSpot sync error detail (when hubspot_sync_failed is true)
        error:
          type: boolean
          description: True only on HTTP 400/500 error responses
      example:
        message: The object was successfully assigned
        success: true
        user: jane@example.com
        field_name: contact_owner
        owner_assigned_at: Thu, 12 Jun 2025 14:30:00 GMT
    ApiError:
      type: object
      required:
        - message
        - error
      properties:
        message:
          type: string
        error:
          type: boolean
          enum:
            - true
        field:
          type: string
          description: Field that caused a conflict (409 duplicate responses)
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer JWT with valid account context.

````