Authentication All company management endpoints require authentication:
Authorization: Bearer <access_token>
Update Company curl -X PATCH "https://api.example.com/api/companies/{id}" \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{ "name": "Acme Corporation Inc.", "description": "Updated company description", "status": "ACTIVE", "metadata": { "industry": "Technology", "size": "200-500", "founded": "2024" } }'
Company’s unique identifier (UUID)
Request Body All fields are optional. Only provide the fields you want to update.
Company name (min: 2, max: 255 characters)
URL-friendly company identifier (min: 2, max: 80 characters). Must contain only lowercase letters, numbers, and hyphens. Must be unique.
URL to company logo image (max: 500 characters). Must be a valid URL. Set to null to remove.
Company description (max: 5000 characters). Set to null to remove.
Additional company metadata as key-value pairs (JSON object). This replaces the entire metadata object.
Company status. Options: ACTIVE, SUSPENDED
Response Indicates if the request was successful
Updated company object Company’s unique identifier (UUID)
URL-friendly company identifier
Additional company metadata
Company status: ACTIVE or SUSPENDED
ISO 8601 timestamp of company creation
ISO 8601 timestamp of last update
{ "success" : true , "data" : { "id" : "660e8400-e29b-41d4-a716-446655440000" , "name" : "Acme Corporation Inc." , "slug" : "acme-corp" , "logo" : "https://example.com/logos/acme.png" , "description" : "Updated company description" , "metadata" : { "industry" : "Technology" , "size" : "200-500" , "founded" : "2024" }, "status" : "ACTIVE" , "createdAt" : "2024-01-01T00:00:00Z" , "updatedAt" : "2024-03-04T11:00:00Z" } }
Only platform admins or users with appropriate company permissions can update company details.
Suspend Company To suspend a company, update its status to SUSPENDED:
curl -X PATCH "https://api.example.com/api/companies/{id}" \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{ "status": "SUSPENDED" }'
Suspending a company will restrict access for all members. They will not be able to access company resources until the status is changed back to ACTIVE.
Delete Company (Soft Delete) curl -X DELETE "https://api.example.com/api/companies/{id}" \ -H "Authorization: Bearer <access_token>"
Company’s unique identifier (UUID)
Response Indicates if the request was successful
{ "success" : true , "message" : "Company deleted successfully" }
This performs a soft delete by setting the deletedAt timestamp. The company data is retained in the database but is hidden from normal queries. Use the restore endpoint to undo this operation.
Restore Deleted Company curl -X POST "https://api.example.com/api/companies/{id}/restore" \ -H "Authorization: Bearer <access_token>"
Company’s unique identifier (UUID)
Response Indicates if the request was successful
{ "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" : {}, "status" : "ACTIVE" , "deletedAt" : null , "createdAt" : "2024-01-01T00:00:00Z" , "updatedAt" : "2024-03-04T11:30:00Z" } }
Restoring a company removes the deletedAt timestamp, making the company visible in normal queries again.
Company Status Values The status field can have one of the following values:
Company is active and operational. Members can access all resources.
Company access is temporarily suspended. Members cannot access company resources.
Error Responses Company Not Found (404 Not Found) { "success" : false , "error" : "Company not found" }
Slug Already Exists (409 Conflict) { "success" : false , "error" : "Company slug already exists" }
Validation Error (400 Bad Request) { "success" : false , "error" : "Validation failed" , "details" : [ { "field" : "status" , "message" : "Invalid status value" } ] }
Permission Denied (403 Forbidden) { "success" : false , "error" : "Insufficient permissions to modify this company" }
Member Management Company member management endpoints allow you to view, invite, and manage members within a company.
Get Company Members GET /api/companies/{id}/members
Company’s unique identifier (UUID)
Returns all active members of the company with their roles and membership details.
Get Non-Members GET /api/companies/{id}/non-members
Returns users who are not members of this company (for inviting purposes).
Update Member Roles PATCH /api/companies/{id}/members/{memberId}/roles
Company’s unique identifier (UUID)
Membership’s unique identifier (UUID)
Array of role UUIDs to assign to the member
Remove Member DELETE /api/companies/{id}/members/{memberId}
Removes a member from the company. This does not delete the user account, only the membership relationship.
Role Management Company role management endpoints allow you to create and manage custom roles within a company.
Get Company Roles GET /api/companies/{id}/roles
Returns all roles defined for the company, including system roles.
Create Custom Role POST /api/companies/{id}/roles
Role name (unique within company)
Hex color code (e.g., “#6366F1”)
Array of permission UUIDs to assign to this role
Update Role PATCH /api/companies/{id}/roles/{roleId}
Updates role name, description, color, or permissions.
Delete Role DELETE /api/companies/{id}/roles/{roleId}
Cannot delete system roles (Owner, Admin, Manager, Member) or roles currently assigned to members.
