Skip to main content

Update Organization

Update an existing organization's details.

Outline

Endpoint​

PATCH /api/v1/organizations/{org_id}

Headers​

HeaderRequiredDescription
AuthorizationYesBearer <access_token>
Content-TypeYesapplication/json

Path Parameters​

ParameterTypeRequiredDescription
org_idintegerYesUnique identifier of the organization to update. You can obtain organization IDs from the List Organizations endpoint.

Request Body​

{
  "name": "Acme Corp Updated",
  "domain": "acme-new.com"
}

Parameters​

FieldTypeRequiredDescription
namestringNoNew organization name. Must be unique across all organizations.
domainstringNoNew organization domain. Used for domain-based features and SSO configuration. Must be a valid domain format.

Response​

Success (200)​

{
  "success": true,
  "data": {
    "organization": {
      "id": 1,
      "name": "Acme Corp Updated",
      "domain": "acme-new.com"
    },
    "message": "Organization updated successfully"
  },
  "message": "Organization updated successfully"
}

Features​

  • Partial Updates: Supports PATCH method, allowing updates to specific fields without requiring all fields
  • Permission Validation: Ensures only organization administrators can update organization details
  • Name Uniqueness: Validates that organization names are unique across the platform
  • Domain Validation: Validates domain format and ensures proper domain configuration
  • Audit Logging: Records all organization update events for security monitoring and compliance

Important Notes​

  • Partial Updates: You only need to include fields you want to update. Omitted fields remain unchanged.
  • Name Uniqueness: Organization names must be unique. If the new name conflicts with an existing organization, the update will fail.
  • Domain Impact: Changing the organization domain may affect SSO configuration and domain-based features. Review SSO configuration if applicable.
  • Immediate Effect: Changes take effect immediately upon successful update.

Error Handling​

Common error scenarios include:

  • Insufficient permissions (not an organization administrator)
  • Organization name already exists
  • Invalid domain format
  • Organization not found

For more information on error handling, see Error Handling.

See Also​