Skip to main content

​
Authentication

All company request endpoints require authentication: 
Authorization: Bearer <access_token>

​
Overview

Company requests allow users to submit requests to create a new company. These requests must be reviewed and approved by platform administrators before the company can be created.
This workflow is an alternative to direct company creation (which requires the COMPANY:CREATE global permission). Users can submit requests without special permissions, and admins can review and approve them.

​
Create Company Request

curl -X POST "https://api.example.com/api/company-requests" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "companyName": "Tech Innovations Inc.",
    "companySlug": "tech-innovations",
    "description": "A company focused on innovative technology solutions",
    "reason": "I would like to create this company to manage our growing team"
  }'

​
Request Body

​
companyName
string
required
Proposed company name (min: 2, max: 255 characters)
​
companySlug
string
required
Proposed URL-friendly company identifier (min: 2, max: 80 characters). Must contain only lowercase letters, numbers, and hyphens.
​
description
string
Company description explaining what the company does
​
reason
string
Reason for requesting company creation (helps admins with approval decision)

​
Response

​
success
boolean
Indicates if the request was successful
​
data
object
Created company request object
​
message
string
Confirmation message
{
  "success": true,
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440000",
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "companyName": "Tech Innovations Inc.",
    "companySlug": "tech-innovations",
    "description": "A company focused on innovative technology solutions",
    "reason": "I would like to create this company to manage our growing team",
    "status": "PENDING",
    "reviewedBy": null,
    "reviewedAt": null,
    "reviewNotes": null,
    "createdCompanyId": null,
    "createdAt": "2024-03-04T10:00:00Z",
    "updatedAt": "2024-03-04T10:00:00Z"
  },
  "message": "Company request submitted successfully. An admin will review it soon."
}

​
List User’s Requests

curl -X GET "https://api.example.com/api/company-requests?status=PENDING&page=1&limit=10" \
  -H "Authorization: Bearer <access_token>"
​
status
string
Filter by request status. Options: PENDING, APPROVED, REJECTED, COMPLETED, CANCELLED
​
page
number
default:"1"
Page number for pagination (minimum: 1)
​
limit
number
default:"10"
Number of results per page (minimum: 1, maximum: 100)

​
Response

​
success
boolean
Indicates if the request was successful
​
data
array
Array of company request objects
​
pagination
object
Pagination metadata
{
  "success": true,
  "data": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440000",
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "companyName": "Tech Innovations Inc.",
      "companySlug": "tech-innovations",
      "description": "A company focused on innovative technology solutions",
      "reason": "I would like to create this company to manage our growing team",
      "status": "PENDING",
      "reviewedBy": null,
      "reviewedAt": null,
      "reviewNotes": null,
      "createdCompanyId": null,
      "createdAt": "2024-03-04T10:00:00Z",
      "updatedAt": "2024-03-04T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 3,
    "totalPages": 1
  }
}

​
Get Request by ID

curl -X GET "https://api.example.com/api/company-requests/{id}" \
  -H "Authorization: Bearer <access_token>"
​
id
string
required
Request’s unique identifier (UUID)

​
Response

​
success
boolean
Indicates if the request was successful
​
data
object
Company request object with user details
{
  "success": true,
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440000",
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "companyName": "Tech Innovations Inc.",
    "companySlug": "tech-innovations",
    "description": "A company focused on innovative technology solutions",
    "reason": "I would like to create this company to manage our growing team",
    "status": "PENDING",
    "reviewedBy": null,
    "reviewedAt": null,
    "reviewNotes": null,
    "createdCompanyId": null,
    "createdAt": "2024-03-04T10:00:00Z",
    "updatedAt": "2024-03-04T10:00:00Z",
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "[email protected]",
      "fullName": "John Doe"
    }
  }
}
Users can only view their own requests. Platform admins can view all requests.

​
Update Request

curl -X PATCH "https://api.example.com/api/company-requests/{id}" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "companyName": "Tech Innovations LLC",
    "description": "Updated company description"
  }'
​
id
string
required
Request’s unique identifier (UUID)

​
Request Body

All fields are optional. Only provide the fields you want to update.
​
companyName
string
Updated company name (min: 2, max: 255 characters)
​
companySlug
string
Updated company slug (min: 2, max: 80 characters). Must contain only lowercase letters, numbers, and hyphens.
​
description
string
Updated company description
​
reason
string
Updated reason for the request

​
Response

​
success
boolean
Indicates if the request was successful
​
data
object
Updated company request object
​
message
string
Confirmation message
{
  "success": true,
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440000",
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "companyName": "Tech Innovations LLC",
    "companySlug": "tech-innovations",
    "description": "Updated company description",
    "reason": "I would like to create this company to manage our growing team",
    "status": "PENDING",
    "reviewedBy": null,
    "reviewedAt": null,
    "reviewNotes": null,
    "createdCompanyId": null,
    "createdAt": "2024-03-04T10:00:00Z",
    "updatedAt": "2024-03-04T10:15:00Z"
  },
  "message": "Company request updated successfully"
}
Only pending requests can be updated. Once a request has been approved, rejected, or cancelled, it cannot be modified.

​
Cancel Request

curl -X POST "https://api.example.com/api/company-requests/{id}/cancel" \
  -H "Authorization: Bearer <access_token>"
​
id
string
required
Request’s unique identifier (UUID)

​
Response

​
success
boolean
Indicates if the request was successful
​
data
object
Cancelled company request object
​
message
string
Confirmation message
{
  "success": true,
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440000",
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "companyName": "Tech Innovations Inc.",
    "companySlug": "tech-innovations",
    "description": "A company focused on innovative technology solutions",
    "reason": "I would like to create this company to manage our growing team",
    "status": "CANCELLED",
    "reviewedBy": null,
    "reviewedAt": null,
    "reviewNotes": null,
    "createdCompanyId": null,
    "createdAt": "2024-03-04T10:00:00Z",
    "updatedAt": "2024-03-04T10:20:00Z"
  },
  "message": "Company request cancelled"
}
Only pending requests can be cancelled. Users can only cancel their own requests.

​
Admin: List All Requests

This endpoint requires platform admin privileges.
curl -X GET "https://api.example.com/api/admin/company-requests?status=PENDING" \
  -H "Authorization: Bearer <access_token>"
​
status
string
Filter by request status. Options: PENDING, APPROVED, REJECTED, COMPLETED, CANCELLED
​
page
number
default:"1"
Page number for pagination
​
limit
number
default:"10"
Number of results per page (max: 100)

​
Response

​
success
boolean
Indicates if the request was successful
​
data
array
Array of all company requests with user details
​
pagination
object
Pagination metadata

​
Admin: Review Request

This endpoint requires platform admin privileges.
curl -X POST "https://api.example.com/api/admin/company-requests/{id}/review" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "approve",
    "reviewNotes": "Request looks good, approved for company creation"
  }'
​
id
string
required
Request’s unique identifier (UUID)

​
Request Body

​
action
string
required
Review action. Options: approve or reject
​
reviewNotes
string
Optional notes about the review decision

​
Response

​
success
boolean
Indicates if the request was successful
​
data
object
Reviewed company request object
​
message
string
Confirmation message
{
  "success": true,
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440000",
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "companyName": "Tech Innovations Inc.",
    "companySlug": "tech-innovations",
    "description": "A company focused on innovative technology solutions",
    "reason": "I would like to create this company to manage our growing team",
    "status": "APPROVED",
    "reviewedBy": "880e8400-e29b-41d4-a716-446655440000",
    "reviewedAt": "2024-03-04T11:00:00Z",
    "reviewNotes": "Request looks good, approved for company creation",
    "createdCompanyId": null,
    "createdAt": "2024-03-04T10:00:00Z",
    "updatedAt": "2024-03-04T11:00:00Z"
  },
  "message": "Company request approved. User can now create their company."
}
When a request is approved, the user receives the COMPANY:CREATE permission and can proceed to create their company. Once the company is created, the request status is updated to COMPLETED and the createdCompanyId is set.

​
Request Status Values

The status field can have one of the following values:
​
PENDING
Request has been submitted and is awaiting admin review
​
APPROVED
Request has been approved by an admin. User can now create the company.
​
REJECTED
Request has been rejected by an admin
​
COMPLETED
Request was approved and the company has been successfully created
​
CANCELLED
Request was cancelled by the user before review

Build docs developers (and LLMs) love

Get started for freeTalk to us