> ## 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.
# Create company
> POST /companies — create a new object
## Endpoint
```http theme={null}
POST https://api.routera.io/companies
```
**Route:** `/companies`\
**Authentication:** Bearer JWT
## Request body
The body is a JSON object with a single `fields` property. Each key inside `fields` is a field **internal\_name** (the same names returned in GET responses, not nested under `fields` in the response).
Include every field you want to set on the new record.
```json theme={null}
{
"fields": {
"external_id": "ext-001",
"company_name": "Acme Corp",
"description": "Example company",
"industry": "Technology"
}
}
```
| Key | Description |
| -------------------- | -------------------------------------------------------------- |
| `fields` | Required. Map of `internal_name` → value for this object type. |
| `fields.external_id` | Optional. External identifier for sync with outside systems. |
Custom fields configured in your account use the same key names inside `fields`.
**Required on create:** At least one of `company_name` or `website_url`. See [API introduction](/api-reference/introduction) for field types and validation rules.
## Default response fields
**201** returns a flat object with these properties:
| Property | Description |
| --------------- | ------------------------------------------------ |
| `id` | Internal object ID |
| `company_name` | Custom or system field (flat on the object) |
| `description` | Custom or system field (flat on the object) |
| `industry` | Custom or system field (flat on the object) |
| `company_owner` | Assigned owner email |
| `external_id` | External identifier (nullable) |
| `archived` | `false` when active; ISO timestamp when archived |
`created_at` and `updated_at` are always included in every response (ISO 8601 UTC), even when not listed above. When an object is **archived**, `archived_by` is also included automatically.
## Response example
```json theme={null}
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"external_id": "ext-001",
"created_at": "2026-05-01T10:00:00.000Z",
"updated_at": "2026-05-28T12:00:00.000Z",
"archived": false,
"company_name": "Acme Corp",
"description": "Example company",
"industry": "Technology",
"company_owner": "jane@example.com"
}
```
## Errors
| Status | When |
| ------ | ------------------------------------------------------------------------------------ |
| `400` | Invalid JSON body, unknown field name, validation failure, or forbidden system field |
| `401` | Missing account context |
| `409` | Duplicate active record (`email`, `website_url`, or `external_id`) |
| `500` | Internal server error |
## OpenAPI
````yaml POST /companies
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:
/companies:
post:
tags:
- Companies
summary: Create company
operationId: createCompany
requestBody:
$ref: '#/components/requestBodies/CompanyCreateBody'
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/Company'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'409':
description: Duplicate active record
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
security:
- bearerAuth: []
components:
requestBodies:
CompanyCreateBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyWriteRequest'
example:
fields:
external_id: ext-001
company_name: Acme Corp
description: Example company
industry: Technology
schemas:
Company:
type: object
properties:
id:
type: string
external_id:
type: string
nullable: true
company_name:
type: string
nullable: true
description:
type: string
nullable: true
industry:
type: string
nullable: true
company_owner:
type: string
nullable: true
description: Assigned owner email
example: jane@example.com
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
archived:
description: false when active, or ISO timestamp when archived
oneOf:
- type: boolean
- type: string
format: date-time
archived_by:
type: string
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)
CompanyWriteRequest:
type: object
required:
- fields
description: >-
Write payload for POST create and PATCH update. Keys inside `fields`
match field internal names returned in GET responses.
properties:
fields:
type: object
description: >-
Field values keyed by internal_name. Custom account fields use the
same key names.
properties:
external_id:
type: string
description: Optional external identifier for sync with outside systems
example: ext-001
x-default: ext-001
company_name:
type: string
example: Acme Corp
x-default: Acme Corp
description: Value for `company_name` (field internal_name)
description:
type: string
example: Example company
x-default: Example company
description: Value for `description` (field internal_name)
industry:
type: string
example: Technology
x-default: Technology
description: Value for `industry` (field internal_name)
additionalProperties: true
example:
fields:
external_id: ext-001
company_name: Acme Corp
description: Example company
industry: Technology
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: Bearer JWT with valid account context.
````