Skip to main content
POST
/
api
/
organizations
curl -X POST https://your-domain.com/api/organizations \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Forest Solutions Inc",
    "rif": "J-456789123",
    "countryId": "660e8400-e29b-41d4-a716-446655440001"
  }'

{
  "id": "880e8400-e29b-41d4-a716-446655440003",
  "name": "Forest Solutions Inc",
  "rif": "J-456789123",
  "countryId": "660e8400-e29b-41d4-a716-446655440001",
  "createdAt": "2024-03-15T10:30:00.000Z"
}

​
Overview

Creates a new organization in the system. This endpoint automatically generates a unique slug from the organization name and validates that no duplicate exists.

​
Authentication

This endpoint requires authentication with specific permissions:
  • SUPER_ADMIN: Full access to create organizations
  • ADMIN (scoped): Cannot create organizations (403 forbidden)
  • Other roles: Require explicit CREATE permission on the organizations module
Scoped administrators (ADMIN role) cannot create new organizations. Only SUPER_ADMIN or users with explicit CREATE permissions can use this endpoint.

​
Request Body

​
name
string
required
Organization nameMust be between 2 and 255 characters. A URL-friendly slug will be automatically generated from this name.
​
rif
string
required
Tax identification number (RIF)Must be between 2 and 60 characters. This will be stored in the organization’s settings.
​
countryId
string
UUID of the country to associate with this organizationOptional field. Must be a valid UUID format or an empty string if provided.

​
Response

Returns the created organization object with a 201 status code.
​
id
string
required
Unique identifier (UUID) for the newly created organization
​
name
string
required
Organization name as provided in the request
​
rif
string
required
Tax identification number as provided in the request
​
countryId
string
UUID of the associated country. Returns null if not provided.
​
createdAt
string
required
ISO 8601 timestamp when the organization was created
curl -X POST https://your-domain.com/api/organizations \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Forest Solutions Inc",
    "rif": "J-456789123",
    "countryId": "660e8400-e29b-41d4-a716-446655440001"
  }'

{
  "id": "880e8400-e29b-41d4-a716-446655440003",
  "name": "Forest Solutions Inc",
  "rif": "J-456789123",
  "countryId": "660e8400-e29b-41d4-a716-446655440001",
  "createdAt": "2024-03-15T10:30:00.000Z"
}

​
Validation Rules

The endpoint validates the request body using Zod schema:
  • name: Required, 2-255 characters
  • rif: Required, 2-60 characters
  • countryId: Optional, must be valid UUID format or empty string

​
Slug Generation

The system automatically generates a URL-friendly slug from the organization name using the generateSlug() utility function. This slug must be unique across all organizations.
If an organization with the same slug already exists (derived from the name), the endpoint will return a 409 Conflict error.

​
Data Model

The created organization has the following structure in the database:
  • id: Auto-generated UUID
  • name: From request body
  • slug: Auto-generated from name
  • countryId: From request body (nullable)
  • settings: JSON object containing { rif: "..." }
  • isActive: Defaults to true
  • createdAt: Auto-generated timestamp
  • updatedAt: Auto-generated timestamp
  • deletedAt: Initially null

​
Permissions

This endpoint checks permissions in the following order:
  1. SUPER_ADMIN: Automatic access
  2. Scoped ADMIN: Explicitly denied (403)
  3. Other users: Must have organizations:CREATE permission

Build docs developers (and LLMs) love

Get started for freeTalk to us