This page provides an API reference for retrieving an organization’s UUID (organizationId) using its domain name. It includes endpoint details, required parameters, example requests, and responses. Use this API when you need to identify your organization for use in other CloudBees Unify API calls.
Retrieve an organization ID
To manage or perform organization-scoped API calls, you need the UUID (organizationId) for your target organization. You can obtain this UUID in one of two ways:
-
Through the CloudBees Unify UI. Refer to Organizations and sub-organizations.
-
Programmatically using the following endpoint, which retrieves an organization’s UUID based on its domain name.
Retrieve an organization’s UUID (organizationId) using its domain name. This endpoint supports partial name matching and returns a list of matching organizations.
GET /v1/organizations?name=<name>
| Parameter name | In | Type | Required? | Description |
|---|---|---|---|---|
|
Query |
String |
Yes |
The domain name of the organization (supports partial matching). |
|
Query |
String |
Yes (for PAT) |
Required when using a personal access token for authentication. |
When authenticating with a personal access token (PAT), you must include the userId parameter in your request.
|
Responses
The following table outlines the possible responses for this endpoint, including status codes, their meanings, and the schemas that describe the structure of the returned data or errors.
| Status Code | Description | Schema |
|---|---|---|
200 |
Success. The request returned a list of organizations matching the provided domain name. |
|
Default |
Error. Occurs when the domain name is missing, invalid, or the user lacks permission. |
|
{ "organizations": [ { "id": "<organization_id>",(1) "displayName": "your organization", "domainName": "<domain_name>" } ] }
| 1 | The organizationId is the UUID returned for each organization that matches your query. |
Alternative endpoint: exact match by name
An alternative endpoint is available for retrieving a specific organization by exact domain name match:
GET /v1/organizations/name?name=<name>
This endpoint only works with tenant organization domain names (not sub-organizations) and requires an exact match. For more flexible queries that support partial matching and sub-organizations, use GET /v1/organizations?name=<name> instead.
|