Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Codefied-CodePix/Karokar-backend/llms.txt

Use this file to discover all available pages before exploring further.

Organizations are the top-level multi-tenancy primitive in KaroKar. Every fleet, every employee group, and every booking ultimately belongs to an organization. The platform supports three distinct organization types — PLATFORM, VENDOR, and CORPORATE — and a full lifecycle expressed through four statuses: PENDING, ACTIVE, SUSPENDED, and REJECTED. Organizations can be nested via the optional parentOrganizationId field, enabling you to model hierarchies such as a corporate parent with regional sub-tenants. Creation is a privileged action protected by the organization.approve permission, reflecting the fact that onboarding a new tenant is a deliberate business decision.

​
POST /organizations

Creates a new organization tenant in the platform. Required permission: organization.approve
A newly created organization is not automatically set to ACTIVE. The initial status is determined by the service layer. Use the updateStatus service method (or a dedicated status-transition endpoint, if exposed) to activate the organization before it can be used in fleet or booking operations.

​
Request body

​
name
string
required
Human-readable display name for the organization. Must be a non-empty string.
​
type
OrganizationType
required
The category of organization. Must be one of the OrganizationType enum values.
​
parentOrganizationId
string (UUID)
Optional UUID of an existing parent organization. Use this to model hierarchical tenant structures, such as a regional division under a national corporate entity.
​
metadata
object
Optional free-form JSON object for storing additional structured data (e.g., GST numbers, contract IDs, regional codes). There is no fixed schema — the object is stored as jsonb and returned as-is.

​
Response

Returns the newly created Organization object.
​
id
string
UUID primary key, auto-generated.
​
name
string
Display name of the organization.
​
type
OrganizationType
One of PLATFORM, VENDOR, or CORPORATE.
​
status
OrganizationStatus
Current lifecycle status of the organization.
​
parentOrganizationId
string | null
UUID of the parent organization, or null for top-level organizations.
​
metadata
object
The free-form JSON object provided at creation time. Defaults to {}.
​
createdAt
string (ISO 8601)
Timestamp of record creation, set automatically by the database.
​
updatedAt
string (ISO 8601)
Timestamp of the last update, maintained automatically by the database.

​
Example

curl -X POST http://localhost:3000/organizations \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Fleet Solutions",
    "type": "VENDOR",
    "parentOrganizationId": null,
    "metadata": {
      "gstNumber": "29ABCDE1234F1Z5",
      "region": "south"
    }
  }'

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "name": "Acme Fleet Solutions",
  "type": "VENDOR",
  "status": "PENDING",
  "parentOrganizationId": null,
  "metadata": {
    "gstNumber": "29ABCDE1234F1Z5",
    "region": "south"
  },
  "createdAt": "2024-06-01T09:00:00.000Z",
  "updatedAt": "2024-06-01T09:00:00.000Z"
}

​
Error cases

StatusReason
401 UnauthorizedMissing or expired Authorization bearer token.
403 ForbiddenAuthenticated principal lacks the organization.approve permission.
400 Bad RequestValidation failure — e.g., type is not a valid OrganizationType, or parentOrganizationId is not a valid UUID.

​
GET /organizations/:id

Retrieves a single organization by its UUID. Required permission: None (authentication is still required via the PermissionGuard).
This endpoint returns null (with a 200 status) when no organization matches the given ID. Always check the response body for null before accessing organization fields in client code.

​
Path parameters

​
id
string
required
The UUID of the organization to retrieve.

​
Response

Returns the matching Organization object, or null if no record exists for the provided ID.
​
id
string
UUID primary key of the organization.
​
name
string
Display name of the organization.
​
type
OrganizationType
One of PLATFORM, VENDOR, or CORPORATE.
​
status
OrganizationStatus
Current lifecycle status: PENDING, ACTIVE, SUSPENDED, or REJECTED.
​
parentOrganizationId
string | null
UUID of the parent organization, or null for top-level organizations.
​
metadata
object
Free-form JSON metadata stored against this organization.
​
createdAt
string (ISO 8601)
Timestamp of record creation.
​
updatedAt
string (ISO 8601)
Timestamp of the last update.

​
Example

curl http://localhost:3000/organizations/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "Authorization: Bearer <token>"

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "name": "Acme Fleet Solutions",
  "type": "VENDOR",
  "status": "ACTIVE",
  "parentOrganizationId": null,
  "metadata": {
    "gstNumber": "29ABCDE1234F1Z5",
    "region": "south"
  },
  "createdAt": "2024-06-01T09:00:00.000Z",
  "updatedAt": "2024-06-02T14:30:00.000Z"
}

​
Error cases

StatusReason
401 UnauthorizedMissing or expired Authorization bearer token.

Build docs developers (and LLMs) love

Get started for freeTalk to us