Sign in

v4

latestOpenAPI 3.1.1Apache 2.02026-07-31107278570.4 KB
Users

Search organization users

Searches for users within a specific organization by email address, user ID, or external ID. The query must be at least 3 characters and is case-insensitive. Scopes results strictly to the given organization. Returns a paginated list of matching users with up to 30 results per page. Use the next_page_token from the response to retrieve subsequent pages.

get/api/v1/organizations/{organization_id}/users:search

Path parameters

organization_idstring required

Unique identifier of the organization to search within. Must start with 'org_' and be 1-32 characters long.

Query parameters

querystring required

Search term to match against user email, IDs, or external IDs. Must be at least 3 characters. Case insensitive.

page_sizeinteger

Maximum number of users to return per page. Value must be between 1 and 30.

page_tokenstring

Token from a previous response for pagination. Provide this to retrieve the next page of results.

Response

Matching users within the organization returned; includes pagination cursors for navigating large result sets.

next_page_tokenstring

Token for retrieving the next page of results. Empty if there are no more pages.

prev_page_tokenstring

Token for retrieving the previous page of results. Empty if this is the first page.

total_sizeinteger

Total number of users matching the request criteria, regardless of pagination.

Example response

{
  "next_page_token": "eyJwYWdlIjogMiwgImxhc3RfaWQiOiAidXNyXzEyMzQ1In0=",
  "prev_page_token": "eyJwYWdlIjogMCwgImZpcnN0X2lkIjogInVzcl85ODc2NSJ9",
  "total_size": 1042,
  "users": [
    {
      "email": "user@example.com",
      "external_id": "ext_12345a67b89c",
      "id": "usr_1234abcd5678efgh",
      "memberships": [
        {
          "display_name": "Acme Corporation",
          "metadata": {
            "department": "engineering",
            "location": "nyc-office"
          },
          "name": "AcmeCorp",
          "organization_id": "org_1234abcd5678efgh",
          "permissions": [
            "read_projects",
            "write_tasks",
            "manage_users"
          ],
          "roles": [
            {
              "display_name": "Dev Team",
              "id": "role_79643236410327240",
              "name": "team_dev"
            }
          ]
        }
      ],
      "metadata": {
        "department": "engineering",
        "location": "nyc-office"
      },
      "user_profile": {
        "custom_attributes": {
          "department": "engineering",
          "security_clearance": "level2"
        },
        "email_verified": true,
        "external_identities": [
          {
            "connection_id": "conn_1234abcd5678efgh",
            "connection_type": "OAUTH",
            "connection_user_id": "ext_user_12345",
            "is_social": true
          }
        ],
        "family_name": "Doe",
        "gender": "male",
        "given_name": "John",
        "groups": [
          "admin",
          "developer"
        ],
        "id": "usr_profile_1234abcd5678efgh",
        "locale": "en-US",
        "metadata": {
          "department": "engineering",
          "employee_type": "full-time",
          "idp_user_id": "12345"
        },
        "name": "John Michael Doe",
        "phone_number": "+14155552671",
        "phone_number_verified": true,
        "picture": "https://example.com/avatar.jpg",
        "preferred_username": "johndoe"
      }
    }
  ]
}