Clerk API (unofficial showcase)
POST/organizations/{organization_id}/domains

Create a new organization domain.

Creates a new organization domain. By default the domain is verified, but can be optionally set to unverified.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 3 body fields
organization_idstringrequired
The ID of the organization where the new domain will be created.
namestringoptional
The name of the new domain
enrollment_modestringoptional
The enrollment_mode for the new domain. This can be `automatic_invitation`, `automatic_suggestion`, `manual_invitation` or `enterprise_sso`
verifiedbooleanoptional
The status of domain's verification. Defaults to true

5 status codes
200An organization domain
objectstringrequired
String representing the object's type. Objects of the same type share the same value. Always `organization_domain`
Allowed:organization_domain
idstringrequired
Unique identifier for the organization domain
organization_idstringrequired
Unique identifier for the organization
namestringrequired
Name of the organization domain
enrollment_modestringrequired
Mode of enrollment for the domain
Allowed:manual_invitationautomatic_invitationautomatic_suggestionenterprise_sso
affiliation_email_addressstringrequired
Affiliation email address for the domain, if available.
affiliation_verificationobjectrequired
Verification details for the user-facing affiliation between the domain and the organization (e.g. affiliation_email_code).
ownership_verificationobjectrequired
Verification details for the underlying DNS domain ownership proof (TXT challenge or dashboard override). Null until ownership has been attempted.
verificationobjectdeprecatedrequired
Deprecated alias for `affiliation_verification`. Kept for backward compatibility on the current API version; will be removed in the next API version. Prefer `affiliation_verification`.
total_pending_invitationsintegerrequired
Total number of pending invitations associated with this domain
total_pending_suggestionsintegerrequired
Total number of pending suggestions associated with this domain
public_organization_dataobjectoptional
Public organization data associated with this domain
created_atintegerrequired
Unix timestamp when the domain was created
updated_atintegerrequired
Unix timestamp of the last update to the domain
400Request was not successful
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
403Authorization invalid
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
404Resource not found
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
422Invalid request parameters
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional

Error handling

A 400 is returned: Request was not successful. A 403 is returned: Authorization invalid. A 404 is returned: Resource not found. A 422 is returned: Invalid request parameters.