> ## Documentation Index
> Fetch the complete documentation index at: https://handbook.nyotaimara.com/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /v1/organizations — Create a New Organization

> Register a new B2B organization on Nyota Imara. Provide a name and a unique slug. The authenticated user is automatically assigned the owner role.

Use this endpoint to create a new organization. The authenticated user becomes the organization owner immediately upon creation. This is a personal context request — no `X-Organization-Id` header is required.

## Endpoint

```
POST https://api.nyotaimara.com/v1/organizations
```

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token. Format: `Bearer <token>`.
</ParamField>

## Body

<ParamField body="name" type="string" required>
  Display name of the organization.
</ParamField>

<ParamField body="slug" type="string" required>
  A unique, URL-safe identifier for the organization. The API lowercases the value and replaces any non-alphanumeric character (except hyphens) with a hyphen — for example, `"Acme Kenya!"` becomes `"acme-kenya-"`. Must be globally unique across all organizations.
</ParamField>

<ParamField body="kraPin" type="string">
  Kenya Revenue Authority PIN for the organization.
</ParamField>

<ParamField body="billingEmail" type="string">
  Email address to receive invoices and billing notifications.
</ParamField>

<ParamField body="address" type="string">
  Physical street address of the organization.
</ParamField>

<ParamField body="city" type="string">
  City where the organization is based.
</ParamField>

<ParamField body="country" type="string" default="Kenya">
  Country of operation. Defaults to `"Kenya"`.
</ParamField>

## Response

<ResponseField name="success" type="boolean" required>
  `true` on a successful creation.
</ResponseField>

<ResponseField name="data" type="object">
  The newly created organization record.

  <Expandable title="data">
    <ResponseField name="id" type="string">
      Unique identifier for the organization.
    </ResponseField>

    <ResponseField name="name" type="string">
      Display name.
    </ResponseField>

    <ResponseField name="slug" type="string">
      Sanitized, unique slug.
    </ResponseField>

    <ResponseField name="kraPin" type="string">
      KRA PIN, if provided.
    </ResponseField>

    <ResponseField name="billingEmail" type="string">
      Billing email address, if provided.
    </ResponseField>

    <ResponseField name="address" type="string">
      Street address, if provided.
    </ResponseField>

    <ResponseField name="city" type="string">
      City, if provided.
    </ResponseField>

    <ResponseField name="country" type="string">
      Country. Defaults to `"Kenya"`.
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  If the slug you provide is already taken by another organization, the API returns a `409 Conflict` error. Choose a different slug and retry.
</Note>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.nyotaimara.com/v1/organizations \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "name": "Acme Kenya Ltd",
      "slug": "acme-kenya",
      "kraPin": "P051234567X",
      "billingEmail": "billing@acmekenya.co.ke",
      "address": "14 Westlands Road",
      "city": "Nairobi",
      "country": "Kenya"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "success": true,
    "data": {
      "id": "org_01j9kxyz",
      "name": "Acme Kenya Ltd",
      "slug": "acme-kenya",
      "kraPin": "P051234567X",
      "billingEmail": "billing@acmekenya.co.ke",
      "address": "14 Westlands Road",
      "city": "Nairobi",
      "country": "Kenya"
    }
  }
  ```

  ```json 409 theme={null}
  {
    "success": false,
    "error": "That organization slug is already taken."
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": "Organization name and unique slug are required."
  }
  ```
</ResponseExample>