Skip to main content

​
Authentication

This endpoint requires authentication and the COMPANY:CREATE global permission or platform admin privileges: 
Authorization: Bearer <access_token>
Only users with the COMPANY:CREATE global permission or platform admins can create companies.

​
Create Company

curl -X POST "https://api.example.com/api/companies" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "slug": "acme-corp",
    "logo": "https://example.com/logos/acme.png",
    "description": "Leading provider of innovative solutions",
    "metadata": {
      "industry": "Technology",
      "size": "50-200"
    },
    "inviteMembers": [
      {
        "email": "[email protected]",
        "roleId": "770e8400-e29b-41d4-a716-446655440000",
        "inviteMessage": "Welcome to Acme Corporation!"
      }
    ]
  }'

​
Request Body

​
name
string
required
Company name (min: 2, max: 255 characters)
​
slug
string
required
URL-friendly company identifier (min: 2, max: 80 characters). Must contain only lowercase letters, numbers, and hyphens. Must be unique across all companies.
URL to company logo image (max: 500 characters). Must be a valid URL.
​
description
string
Company description (max: 5000 characters)
​
metadata
object
Additional company metadata as key-value pairs (JSON object). Can store custom fields like industry, size, etc.
​
inviteMembers
array
Optional array of members to invite to the company upon creation

​
Response

​
success
boolean
Indicates if the request was successful
​
data
object
Created company object with default roles and creator membership
{
  "success": true,
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440000",
    "name": "Acme Corporation",
    "slug": "acme-corp",
    "logo": "https://example.com/logos/acme.png",
    "description": "Leading provider of innovative solutions",
    "metadata": {
      "industry": "Technology",
      "size": "50-200"
    },
    "status": "ACTIVE",
    "roles": [
      {
        "id": "770e8400-e29b-41d4-a716-446655440000",
        "name": "Owner",
        "description": "Company owner with full access",
        "color": "#EF4444",
        "isSystem": true,
        "isDefault": false
      },
      {
        "id": "880e8400-e29b-41d4-a716-446655440000",
        "name": "Admin",
        "description": "Administrator with elevated privileges",
        "color": "#F59E0B",
        "isSystem": true,
        "isDefault": false
      },
      {
        "id": "990e8400-e29b-41d4-a716-446655440000",
        "name": "Manager",
        "description": "Manager with team oversight",
        "color": "#3B82F6",
        "isSystem": false,
        "isDefault": false
      },
      {
        "id": "aa0e8400-e29b-41d4-a716-446655440000",
        "name": "Member",
        "description": "Standard member",
        "color": "#6B7280",
        "isSystem": true,
        "isDefault": true
      }
    ],
    "membership": {
      "id": "bb0e8400-e29b-41d4-a716-446655440000",
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "companyId": "660e8400-e29b-41d4-a716-446655440000",
      "status": "ACTIVE",
      "roles": [
        {
          "id": "770e8400-e29b-41d4-a716-446655440000",
          "name": "Owner"
        }
      ]
    },
    "createdAt": "2024-03-04T10:00:00Z",
    "updatedAt": "2024-03-04T10:00:00Z"
  }
}

​
Default Roles

When a company is created, four default roles are automatically created:
  1. Owner (System Role)
    • Color: #EF4444 (Red)
    • Full access to all company resources
    • Assigned to the company creator
    • Cannot be deleted
  2. Admin (System Role)
    • Color: #F59E0B (Orange)
    • Elevated privileges for company administration
    • Cannot be deleted
  3. Manager (Custom Role)
    • Color: #3B82F6 (Blue)
    • Team oversight and management
    • Can be modified or deleted
  4. Member (System Role, Default)
    • Color: #6B7280 (Gray)
    • Standard member access
    • Default role for new members
    • Cannot be deleted
The company creator is automatically assigned the Owner role with ACTIVE status.

​
Error Responses

​
error
string
Error message describing what went wrong

​
Slug Already Exists (409 Conflict)

{
  "success": false,
  "error": "Company slug already exists"
}

​
Validation Error (400 Bad Request)

{
  "success": false,
  "error": "Validation failed",
  "details": [
    {
      "field": "slug",
      "message": "Slug must contain only lowercase letters, numbers, and hyphens"
    }
  ]
}

​
Permission Denied (403 Forbidden)

{
  "success": false,
  "error": "Insufficient permissions to create a company"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us