API introduction

Base URL

https://api.routera.io

All paths in this reference are relative to that base URL.

Authentication

Integrations authenticate using the OAuth 2.0 client credentials grant.

1. Obtain an access token

POST /oauth2/token exchanges client_id and client_secret for a JWT. See Obtain access token for the full request format.

POST https://api.routera.io/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET

The response includes access_token, expires_in, and token_type (Bearer). There is no refresh token — request a new access token when it expires.

2. Call the API

Every other route requires the access token:

Authorization: Bearer <access_token>

The JWT must include a valid account context (set automatically for integrations linked to your account). Requests without it receive 401 with:

{ "message": "Unauthorized: missing account context", "error": true }

Routes

Authentication

Route	HTTP
`/oauth2/token`	POST

Objects API

Route	HTTP
`/contacts`, `/companies`, `/deals`, `/tickets`	GET, POST
`/contacts/{contactId}`, `/companies/{companyId}`, `/deals/{dealId}`, `/tickets/{ticketId}`	GET, PATCH, DELETE

Routers API

Route	HTTP
`/routers`	GET
`/routers/{routerId}`	GET

Dispatch

Route	HTTP
`/dispatch/router`	POST

Object types

The object type is inferred from the path segment:

Path segment	Object type	Default response fields
`/contacts`	contacts	`id`, `first_name`, `last_name`, `email`, `contact_owner`, `external_id`, `archived`
`/companies`	companies	`id`, `company_name`, `description`, `industry`, `company_owner`, `external_id`, `archived`
`/deals`	deals	`id`, `deal_name`, `pipeline`, `deal_stage`, `deal_owner`, `external_id`, `archived`
`/tickets`	tickets	`id`, `ticket_name`, `pipeline`, `ticket_owner`, `external_id`, `archived`

Every response also includes created_at and updated_at (ISO 8601 UTC). When an object is archived, archived_by is added automatically.

Response format

All object endpoints return a flat JSON object. Custom field values appear at the top level next to id and external_id (there is no nested fields object).

Archived objects

State	`archived`	`archived_by`
Active	`false`	omitted
Archived	ISO timestamp string	user or API client id who archived

DELETE archives the object; the record is retained with archived set to a timestamp.

Default properties

When the properties query parameter is omitted, each type returns its default field set from the table above, plus created_at and updated_at. Use ?properties=phone to request additional fields beyond the defaults (not a replacement list). Invalid or disallowed property names return 400. Supported on GET list, GET by id, and PATCH update responses.

List pagination

GET on a collection returns:

{
  "data": [ /* objects */ ],
  "pagination": { "limit": 10, "offset": 0, "count": 1 }
}

Query parameters: limit (default 10, max 100), offset (default 0), archived=true to include archived rows.

Write requests

POST (create) and PATCH (update) use the same JSON shape: a top-level fields object whose keys are field internal names.

{
  "fields": {
    "external_id": "ext-001",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "email": "ada@example.com"
  }
}

On create, send the fields you want to set. On update, send only the fields you want to change. POST responds with 201 and the created object.

System-managed fields

These fields cannot be sent in body.fields. Attempts return 400 (for example Field cannot be set: record_id):

Field	When set automatically
`record_id`	Database on create — not set by the Objects API
`create_date`	POST create
`last_modified_date`	Every POST create and PATCH update
`*_owner_assigned_date`	When an owner field is included in the request
`created_at`, `updated_at`	Object-table timestamps; always in responses, never writable via `fields`

These fields remain readable via ?properties= on GET and PATCH responses.

Field validation

Validation is atomic: if any field in body.fields fails, the entire create or update is rejected with 400 and nothing is written.

`field_type_id`	Accepted input	Stored value
`string`	String (or coercible)	String (`email` lowercased; `website_url` stored as canonical host/domain)
`number`	Finite number	String
`bool`	`true`, `false`, `"true"`, `"false"`	`"true"` or `"false"`
`datetime`	ISO 8601, RFC 2822, or numeric timestamp	ISO 8601 UTC string
`enumeration`	`internal_name` or display `name` (case-insensitive)	`internal_name` from DB field values
`user`	User UUID or email	Email string

Enumeration allowed values come from the database (field.values for that field), including options added in the app — not a fixed list in code.

Required fields (POST create only)

Object type	Requirement
`contacts`	At least one of `email`, `first_name`, `last_name`
`companies`	At least one of `company_name`, `website_url`
`deals`	`deal_name`, `deal_stage`, `pipeline`
`tickets`	`ticket_name`, `ticket_stage`, `pipeline`

PATCH does not require these fields, but every key in fields must exist on the object type and pass type validation.

Duplicate prevention (POST / PATCH)

POST and PATCH reject duplicate active records (non-archived) within the same account and object type. Conflicts return 409 with field indicating which key collided.

Object type	Unique keys checked (when present in `body.fields` or as `external_id`)
`contacts`	`email`, `external_id`
`companies`	`website_url`, `external_id`
`deals`	`external_id`
`tickets`	`external_id`

Deals and tickets have no other business unique keys; duplicate deal_name / ticket_name values are allowed unless external_id is provided. Example responses:

{
  "message": "A contact with this email already exists",
  "error": true,
  "field": "email"
}

{
  "message": "A deal with this external_id already exists",
  "error": true,
  "field": "external_id"
}

Re-sending the same POST body with the same key does not create a second record.
website_url variants such as https://www.foo.com and foo.com are treated as the same company.
Archived records are ignored; a new active record may reuse a key from an archived one.
Concurrent requests with the same key may still race without a database unique constraint (application-level check only).

Routers

GET /routers returns a paginated list of routers for the authenticated account. GET /routers/{routerId} returns a single router with flattened settings, users, and teams. See List routers and Get router.

Dispatch

POST /dispatch/router runs router assignment for an object. The body must include router_id and object_id. See Dispatch router.

Create records

Product overview for records and fields in Routera.

Overview

Authentication

Contacts

Companies

Deals

Tickets

Routers

Dispatch

Base URL

Authentication

1. Obtain an access token

2. Call the API

Routes

Authentication

Objects API

Routers API

Dispatch

Object types

Response format

Archived objects

Default properties

Write requests

System-managed fields

Field validation

Required fields (POST create only)

Duplicate prevention (POST / PATCH)

Routers

Dispatch

Create records

​Base URL

​Authentication

​1. Obtain an access token

​2. Call the API

​Routes

​Authentication

​Objects API

​Routers API

​Dispatch

​Object types

​Response format

​Archived objects

​Default properties

​List pagination

​Write requests

​System-managed fields

​Field validation

​Required fields (POST create only)

​Duplicate prevention (POST / PATCH)

​Routers

​Dispatch

​Related guides

Create records

Base URL

Authentication

1. Obtain an access token

2. Call the API

Routes

Authentication

Objects API

Routers API

Dispatch

Object types

Response format

Archived objects

Default properties

List pagination

Write requests

System-managed fields

Field validation

Required fields (POST create only)

Duplicate prevention (POST / PATCH)

Routers

Dispatch

Related guides