Create Company

POST /companies

Create Company

cURL

curl --request POST \
  --url https://api.example.com/companies \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "slug": "<string>",
  "industry": "<string>",
  "country": "<string>",
  "timezone": "<string>",
  "currency": "<string>",
  "registration_number": "<string>",
  "tax_id": "<string>",
  "address": "<string>",
  "phone": "<string>",
  "logo_url": "<string>",
  "status": "<string>",
  "admin": {
    "admin.email": "<string>",
    "admin.password": "<string>",
    "admin.first_name": "<string>",
    "admin.last_name": "<string>",
    "admin.phone": "<string>"
  }
}
'

200

{
  "success": true,
  "data": {
    "data.id": "<string>",
    "data.name": "<string>",
    "data.slug": "<string>",
    "data.industry": "<string>",
    "data.country": "<string>",
    "data.timezone": "<string>",
    "data.currency": "<string>",
    "data.registration_number": "<string>",
    "data.tax_id": "<string>",
    "data.address": "<string>",
    "data.phone": "<string>",
    "data.logo_url": "<string>",
    "data.status": "<string>",
    "data.settings": {},
    "data.created_at": "<string>",
    "data.updated_at": "<string>"
  }
}

Create a new company with an admin user. This endpoint creates both the company and its initial administrator account.

Request Body

name · string · required

Company name (2-255 characters)

slug · string · required

Unique company identifier (2-255 characters)

industry · string

Industry sector (max 100 characters)

country · string

Country location (max 100 characters)

timezone · string

Timezone identifier (max 50 characters)

currency · string

Currency code (max 10 characters)

registration_number · string

Business registration number (max 100 characters)

tax_id · string

Tax identification number (max 100 characters)

address · string

Physical address

phone · string

Contact phone number (max 100 characters)

logo_url · string

URL to company logo

status · string

Company status. One of: active, suspended, inactive

admin · object · required

Administrator account details

admin.email · string · required

Admin email address (must be valid email)

admin.password · string · required

Admin password (minimum 8 characters)

admin.first_name · string · required

Admin first name

admin.last_name · string · required

Admin last name

admin.phone · string

Admin phone number

Response

success · boolean

Indicates if the request was successful

data · object

The created company object

data.id · string

Company UUID

data.name · string

Company name

data.slug · string

Company slug identifier

data.industry · string

Industry sector

data.country · string

Country location

data.timezone · string

Timezone identifier

data.currency · string

Currency code

data.registration_number · string

Registration number

data.tax_id · string

Tax identification

data.address · string

Physical address

data.phone · string

Contact phone

data.logo_url · string

Logo URL

data.status · string

Company status

data.settings · object

Company settings (JSON)

data.created_at · string

Creation timestamp (ISO 8601)

data.updated_at · string

Last update timestamp (ISO 8601)

Request Example

cURL

curl -X POST https://api.companyflow.com/companies \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "slug": "acme-corp",
    "industry": "Technology",
    "country": "United States",
    "timezone": "America/New_York",
    "currency": "USD",
    "registration_number": "123456789",
    "tax_id": "98-7654321",
    "address": "123 Main St, New York, NY 10001",
    "phone": "[phone]",
    "status": "active",
    "admin": {
      "email": "[e-mail]",
      "password": "SecurePass123!",
      "first_name": "John",
      "last_name": "Doe",
      "phone": "[phone]"
    }
  }'

Response Example

201 Created

{
  "success": true,
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Acme Corporation",
    "slug": "acme-corp",
    "industry": "Technology",
    "country": "United States",
    "timezone": "America/New_York",
    "currency": "USD",
    "registration_number": "123456789",
    "tax_id": "98-7654321",
    "address": "123 Main St, New York, NY 10001",
    "phone": "[phone]",
    "logo_url": "",
    "status": "active",
    "settings": null,
    "created_at": "2026-03-03T10:00:00Z",
    "updated_at": "2026-03-03T10:00:00Z"
  }
}

400 Bad Request

{
  "success": false,
  "message": "invalid request body"
}

400 Validation Error

{
  "success": false,
  "message": "name is required"
}

500 Internal Server Error

{
  "success": false,
  "message": "internal server error"
}

Error Responses

Status Code	Description
400	Invalid request body or validation error
500	Internal server error