---
title: "Create a new company"
method: POST
path: "/companies"
tags: ["Companies"]
---

# Create a new company

`POST /companies`

Create a new company within an organization

## Request body

- CompanyInput
  - `name` string, required — Company legal name
  - `addressLine1` string — Primary street address
  - `addressLine2` string — Secondary address line (suite, floor, etc.)
  - `city` string — City name
  - `country` string — Country code or name
  - `fax` string — Fax number
  - `invoiceOnly` boolean — Whether this company is used only for invoicing purposes
  - `invoiceVerbiage` string — Custom text to include on invoices for this company
  - `primaryContactName` string — Name of primary contact person
  - `primaryContactEmail` string, email — Email address of primary contact
  - `primaryContactPhone` string — Phone number of primary contact
  - `key` string — Client-defined reference identifier

## Response `201`

Company created successfully

- Company
  - `object` 'COMPANY' — Object type identifier
  - `id` string, uuid, required — Unique company identifier
  - `name` string, required — Company legal name
  - `addressLine1` string, nullable — Primary street address
  - `addressLine2` string, nullable — Secondary address line (suite, floor, etc.)
  - `city` string, nullable — City name
  - `country` string, nullable — Country code or name
  - `fax` string, nullable — Fax number
  - `invoiceOnly` boolean, nullable — Whether this company is used only for invoicing purposes
  - `invoiceVerbiage` string, nullable — Custom text to include on invoices for this company
  - `primaryContactName` string, nullable — Name of primary contact person
  - `primaryContactEmail` string, email, nullable — Email address of primary contact
  - `primaryContactPhone` string, nullable — Phone number of primary contact
  - `createdBy` UserReference — Enhanced reference to a user resource (returned in responses). Includes full user details in addition to id/key. Note: Does NOT include nested references (teams, etc.) to prevent recursion. Maximum nesting depth: 1 level.
    - `id` string, uuid, required — User UUID
    - `key` string, nullable — Client-defined reference ID if set
    - `email` string, email, required — User's email address
    - `name` string, nullable — User's full name
    - `phone` string, nullable — User's phone number
    - `phoneExt` string, nullable — Phone extension
    - `status` 'PENDING' | 'ACTIVE' | 'INACTIVE', required — User account status
    - `avatarId` string, uuid, nullable — Profile avatar document ID
    - `createdAt` string, date-time, required — When the user was created
    - `updatedAt` string, date-time, required — When the user was last updated
    - `deletedAt` string, date-time, nullable — When the user was soft deleted (null if active)
  - `key` string, nullable — Client-defined reference identifier
  - `createdAt` string, date-time, required — When the company was created
  - `updatedAt` string, date-time, required — When the company was last updated
  - `deletedAt` string, date-time, nullable — When the company was soft deleted (null if active)

## Other responses

- `400` — Bad request - invalid input
- `401` — Unauthorized - invalid or missing access token
- `409` — Conflict - resource already exists or constraint violation
- `500` — Internal server error

---

[API](https://skmtc.net/mvmnt/apis/mvmnt-api.md) · [All operations](https://skmtc.net/mvmnt/apis/mvmnt-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mvmnt/mvmnt-api/revisions/53b310bb74a0/schema)