Skip to main content
Update an existing organization’s details. Requires admin/owner permissions on the organization.

​
Path Parameters

​
id
string
required
The organization identifier. Can be either:
  • Organization UUID (e.g., 9f256f86-d3c4-4a6e-b89a-1e9a23c5d78e)
  • Organization name/slug (e.g., acme-corp)

​
Request Body

​
body
object
required
Organization fields to update. Only provided fields will be updated.
​
name
string
Unique name/slug for the organization. Must be lowercase, alphanumeric with hyphens.Warning: Changing the name affects all URLs and API references.Example: acme-corporation, new-org-name
​
title
string
Human-readable display name for the organization.Example: Acme Corporation, New Organization Name
​
avatar
string
URL to the organization’s avatar image. Set to empty string to remove.Example: https://example.com/avatars/new-logo.png
​
metadata
object
Custom metadata for the organization. This completely replaces existing metadata - use a partial update pattern in your application if you want to preserve existing fields.Example: {"industry": "fintech", "employees": 500, "region": "eu-west"}

​
Response

​
organization
object
The updated organization object.
​
id
string
Unique identifier for the organization (UUID format).
​
name
string
Updated unique name/slug for the organization.
​
title
string
Updated human-readable display name.
​
avatar
string
Updated avatar URL.
​
state
string
Current state of the organization (unchanged by this endpoint).
​
metadata
object
Updated custom metadata.
​
created_at
timestamp
Original creation timestamp (unchanged).
​
updated_at
timestamp
Timestamp of this update (RFC3339 format).
curl -X PUT 'https://api.frontier.example.com/v1beta1/organizations/acme-corp' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "body": {
      "title": "Acme Corporation Inc.",
      "avatar": "https://example.com/avatars/acme-new.png",
      "metadata": {
        "industry": "technology",
        "size": "enterprise",
        "employees": 5000
      }
    }
  }'

​
Response Example

{
  "organization": {
    "id": "9f256f86-d3c4-4a6e-b89a-1e9a23c5d78e",
    "name": "acme-corp",
    "title": "Acme Corporation Inc.",
    "avatar": "https://example.com/avatars/acme-new.png",
    "state": "enabled",
    "metadata": {
      "industry": "technology",
      "size": "enterprise",
      "employees": 5000
    },
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-03-03T15:45:00Z"
  }
}

​
Error Responses

​
code
string
Error code indicating the type of error.
​
message
string
Human-readable error message.

​
Common Errors

  • 400 Bad Request: Invalid request body or field values
    • Invalid organization name format
    • Metadata doesn’t match the required schema
    • Empty request body
  • 401 Unauthorized: Invalid or missing authentication token
  • 404 Not Found: Organization doesn’t exist
  • 409 Conflict: New organization name already exists (if changing name)
  • 500 Internal Server Error: Server encountered an unexpected error

​
Notes

  • Only organization admins/owners can update organization details
  • You can update individual fields without providing all fields
  • Changing the organization name affects all URLs and API references
  • Metadata is replaced entirely, not merged - include all metadata fields you want to keep
  • An audit log entry is created for the organization update event
  • The updated_at timestamp is automatically set to the current time
  • To remove the avatar, set it to an empty string
  • Organization state cannot be changed through this endpoint - use enable/disable endpoints instead

Build docs developers (and LLMs) love

Get started for freeTalk to us