Create Company API

Overview

Onboards a new corporate client / company and simultaneously creates the company's primary Company Admin user (with role COMPANY_ADMIN) in a single atomic database transaction.

• Endpoint: /api/companies/create
• Method: POST
• Auth Required: Yes (Bearer <token>)
• Access Role: Super Admin / Platform RM

---

Request Body Schema

Field	Type	Required	Default	Description
name	String	Yes	—	Display name of the company
legalName	String	No	null	Registered legal entity name
gstin	String	No	null	15-character GST identification number
gstType	Enum	No	null	REGISTERED, UNREGISTERED, COMPOSITION, or SEZ
panNumber	String	No	null	10-character Permanent Account Number
address	String	No	null	Office street address
stateId	Number (Integer)	No	null	Foreign key ID referencing the State master record
pincode	String	No	null	Area postal pincode
phone	String	No	null	Corporate contact phone number
emailId	String	No	null	Official corporate contact email
website	String (URL)	No	null	Corporate website URL
creditLimit	Number	No	500000	Total credit limit granted (>= 0)
creditDays	Number (Integer)	No	15	Credit payment window in days (>= 0)
priceToleranceType	Enum	No	"PERCENTAGE"	Price tolerance strategy: PERCENTAGE or FLAT
priceTolerancePercent	Number	No	5	Allowed booking price escalation percentage (0 to 100)
priceToleranceAmount	Number	No	null	Allowed booking price escalation flat amount (>= 0)
adminUser	Object	No	null	Primary Company Admin user creation payload

---

adminUser Object Schema

Field	Type	Required	Default	Description
firstName	String	Yes	—	Admin user's first name
lastName	String	No	null	Admin user's last name
email	String	Yes	—	Unique corporate email address for login
password	String	No	"Password123!"	Admin login password (minimum 6 characters)
phone	String	No	null	Unique contact phone number for admin user

---

Request Body Example

{
  "name": "Abbott Healthcare",
  "legalName": "Abbott Healthcare India Private Limited",
  "gstin": "27AAACA0000A1Z5",
  "gstType": "REGISTERED",
  "panNumber": "AAACA0000A",
  "address": "123 Business Park, BKC",
  "stateId": 21,
  "pincode": "400051",
  "phone": "+912212345678",
  "emailId": "info@abbott.com",
  "website": "https://www.abbott.com",
  "creditLimit": 1000000,
  "creditDays": 30,
  "priceToleranceType": "PERCENTAGE",
  "priceTolerancePercent": 5,
  "adminUser": {
    "firstName": "Anita",
    "lastName": "Iyer",
    "email": "admin@abbott.com",
    "password": "Password123!",
    "phone": "+919876543210"
  }
}

---

Success Response (201 Created)

{
  "success": true,
  "message": "Company onboarded successfully",
  "data": {
    "company": {
      "id": "c478a846-993d-4c8d-bf8d-d77cb3370e01",
      "name": "Abbott Healthcare",
      "legalName": "Abbott Healthcare India Private Limited",
      "gstin": "27AAACA0000A1Z5",
      "gstType": "REGISTERED",
      "panNumber": "AAACA0000A",
      "address": "123 Business Park, BKC",
      "stateId": 21,
      "pincode": "400051",
      "phone": "+912212345678",
      "emailId": "info@abbott.com",
      "website": "https://www.abbott.com",
      "creditLimit": "1000000.00",
      "creditDays": 30,
      "priceToleranceType": "PERCENTAGE",
      "priceTolerancePercent": 5,
      "priceToleranceAmount": null,
      "active": true,
      "delete": false,
      "createdAt": "2026-09-02T07:30:00.000Z",
      "updatedAt": "2026-09-02T07:30:00.000Z",
      "employeeBands": [],
      "departments": [],
      "users": [
        {
          "id": "u555-admin-uuid",
          "email": "admin@abbott.com",
          "firstName": "Anita",
          "lastName": "Iyer",
          "employeeBand": null
        }
      ],
      "_count": {
        "users": 1,
        "bookings": 0
      }
    },
    "adminUser": {
      "id": "u555-admin-uuid",
      "email": "admin@abbott.com",
      "firstName": "Anita",
      "lastName": "Iyer",
      "phone": "+919876543210",
      "companyId": "c478a846-993d-4c8d-bf8d-d77cb3370e01",
      "bandId": null,
      "employeeBand": null,
      "clientType": "B2B",
      "active": true,
      "delete": false,
      "createdAt": "2026-09-02T07:30:00.000Z",
      "updatedAt": "2026-09-02T07:30:00.000Z"
    }
  }
}

---

Error Responses

400 Bad Request — Validation Error

{
  "success": false,
  "data": {
    "name": {
      "_errors": ["Company display name is required"]
    }
  },
  "message": "Validation failed"
}

400 Bad Request — Duplicate Company Name

{
  "success": false,
  "data": null,
  "message": "Active company with name 'Abbott Healthcare' already exists"
}

400 Bad Request — Duplicate Admin Email

{
  "success": false,
  "data": null,
  "message": "User with email 'admin@abbott.com' already exists"
}

---

Database Impact

• Tables Affected: Company, User, UserSystemRoleMap, CompanyUserRole
• Transaction: Performed inside an atomic Prisma transaction (prisma.$transaction).