Organizations API

Organizations represent the companies you are selling to (e.g., retail shops, business customers). Each organization belongs to your company and can have multiple contacts, deals, and related data.

Endpoints Overview

Method	Endpoint	Description
GET	`/api-v1-organizations`	List all organizations with filtering, sorting, and pagination
GET	`/api-v1-organizations/:id`	Get a single organization by ID
POST	`/api-v1-organizations`	Create a new organization
PATCH	`/api-v1-organizations/:id`	Update an existing organization
DELETE	`/api-v1-organizations/:id`	Soft delete an organization

Required Scopes

Read operations: read:organizations
Write operations: write:organizations

List Organizations

List all organizations with support for filtering, sorting, and pagination.

Endpoint: GET /api-v1-organizations

Scope: read:organizations

Query Parameters

Pagination

Parameter	Type	Default	Description
`limit`	integer	50	Number of records per page (max: 100)
`page`	integer	1	Page number for offset-based pagination
`per_page`	integer	50	Alternative to `limit` for offset-based pagination
`cursor`	string	-	Cursor for cursor-based pagination

Filtering

Filters can be applied using the following syntax:

Simple equality: ?name=Acme Corp
With operator: ?name[like]=Acme or ?created_at[gte]=2024-01-01

Supported operators: eq, ne, gt, gte, lt, lte, like, in

Filterable fields:

name - Organization name (string)
status - Organization status (enum: lead, active, inactive, lost)
organization_type - Type of organization (string)
city - City location (string)
country - Country location (string)
created_at - Creation timestamp (ISO 8601)

Sorting

Use the sort parameter with field name. Prefix with - for descending order.

Examples:

?sort=name - Sort by name ascending
?sort=-created_at - Sort by creation date descending

Sortable fields: name, created_at, updated_at, status

Response

Returns a paginated list of organizations.

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Acme Retail Shop",
      "status": "active",
      "organization_type": "retail",
      "address": "123 Main St",
      "city": "Berlin",
      "state": "Berlin",
      "postal_code": "10115",
      "country": "Germany",
      "domain": "acme-shop.de",
      "metadata": {},
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 100,
    "limit": 50,
    "page": 1,
    "per_page": 50,
    "total_pages": 2,
    "has_more": true
  }
}

Example Request

curl -X GET "https://your-project.supabase.co/functions/v1/api-v1-organizations?limit=20&status=active&sort=-created_at" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Single Organization

Retrieve a single organization by its unique ID.

Endpoint: GET /api-v1-organizations/:id

Scope: read:organizations

Path Parameters

Parameter	Type	Required	Description
`id`	UUID	Yes	Organization ID

Response

Returns a single organization object.

{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Acme Retail Shop",
    "status": "active",
    "organization_type": "retail",
    "address": "123 Main St",
    "city": "Berlin",
    "state": "Berlin",
    "postal_code": "10115",
    "country": "Germany",
    "domain": "acme-shop.de",
    "metadata": {},
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

Example Request

curl -X GET "https://your-project.supabase.co/functions/v1/api-v1-organizations/123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Error Responses

404 Not Found:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Organization not found"
  }
}

Create Organization

Create a new organization in your CRM.

Endpoint: POST /api-v1-organizations

Scope: write:organizations

Request Body

Field	Type	Required	Description
`name`	string	Yes	Organization name (trimmed, non-empty)
`status`	enum	No	Status: `lead`, `active`, `inactive`, `lost` (default: `lead`)
`organization_type`	string	No	Type of organization (e.g., “retail”, “wholesale”)
`address`	string	No	Street address
`city`	string	No	City
`state`	string	No	State or region
`postal_code`	string	No	Postal/ZIP code
`country`	string	No	Country
`domain`	string	No	Website domain
`metadata`	object	No	Custom metadata as JSON object

Response

Returns the created organization with a 201 Created status.

{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Acme Retail Shop",
    "status": "lead",
    "organization_type": "retail",
    "address": "123 Main St",
    "city": "Berlin",
    "state": "Berlin",
    "postal_code": "10115",
    "country": "Germany",
    "domain": "acme-shop.de",
    "metadata": {},
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

Example Request

curl -X POST "https://your-project.supabase.co/functions/v1/api-v1-organizations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Retail Shop",
    "status": "lead",
    "organization_type": "retail",
    "city": "Berlin",
    "country": "Germany",
    "domain": "acme-shop.de"
  }'

Error Responses

400 Validation Error (missing name):

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Name is required",
    "details": [
      {
        "field": "name",
        "message": "Name is required"
      }
    ]
  }
}

400 Validation Error (invalid status):

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid status. Must be one of: lead, active, inactive, lost",
    "details": [
      {
        "field": "status",
        "message": "Must be one of: lead, active, inactive, lost"
      }
    ]
  }
}

Update Organization

Update an existing organization. Only provided fields will be updated.

Endpoint: PATCH /api-v1-organizations/:id

Scope: write:organizations

Path Parameters

Parameter	Type	Required	Description
`id`	UUID	Yes	Organization ID

Request Body

All fields are optional. Only include fields you want to update.

Field	Type	Description
`name`	string	Organization name
`status`	enum	Status: `lead`, `active`, `inactive`, `lost`
`organization_type`	string	Type of organization
`address`	string	Street address
`city`	string	City
`state`	string	State or region
`postal_code`	string	Postal/ZIP code
`country`	string	Country
`domain`	string	Website domain
`metadata`	object	Custom metadata (replaces existing)

Response

Returns the updated organization.

{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Acme Retail Shop",
    "status": "active",
    "organization_type": "retail",
    "address": "456 New Address",
    "city": "Berlin",
    "state": "Berlin",
    "postal_code": "10115",
    "country": "Germany",
    "domain": "acme-shop.de",
    "metadata": {},
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-16T14:20:00Z"
  }
}

Example Request

curl -X PATCH "https://your-project.supabase.co/functions/v1/api-v1-organizations/123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "active",
    "address": "456 New Address"
  }'

Error Responses

404 Not Found:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Organization not found"
  }
}

400 No Fields:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "No fields to update"
  }
}

Delete Organization

Soft delete an organization. The organization is not permanently deleted but marked with a deleted_at timestamp and will no longer appear in API responses.

Endpoint: DELETE /api-v1-organizations/:id

Scope: write:organizations

Path Parameters

Parameter	Type	Required	Description
`id`	UUID	Yes	Organization ID

Response

Returns a deletion confirmation.

{
  "data": {
    "deleted": true
  }
}

Example Request

curl -X DELETE "https://your-project.supabase.co/functions/v1/api-v1-organizations/123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Error Responses

404 Not Found:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Organization not found"
  }
}

Status Field

The status field represents the current relationship status with the organization:

Value	Description
`lead`	Potential customer, not yet qualified
`active`	Active customer with ongoing business
`inactive`	Former customer or inactive account
`lost`	Lost opportunity, not a customer

Multi-Tenant Isolation

All organizations are automatically scoped to your company. You can only access organizations that belong to your company (determined by your API key’s company_id).

Contacts: Organizations can have multiple contacts. See Contacts API
Deals: Organizations can have multiple deals. See Deals API

Organizations API

Organizations API

Endpoints Overview

Required Scopes

List Organizations

Query Parameters

Pagination

Filtering

Sorting

Response

Example Request

Get Single Organization

Path Parameters

Response

Example Request

Error Responses

Create Organization

Request Body

Response

Example Request

Error Responses

Update Organization

Path Parameters

Request Body

Response

Example Request

Error Responses

Delete Organization

Path Parameters

Response

Example Request

Error Responses

Status Field

Multi-Tenant Isolation

Related Resources