List of Users

The user data is encrypted and does not have blind index searching.

Use the search endpoint to search for personal identifyable information such as first name, last name, full name, employee ID, etc.

GET /directory/users

List of Users

cURL

curl --request GET \
  --url https://wks-a1b2c3d4.provisionr.io/api/v1/directory/users \
  --header 'Authorization: Bearer <token>'

200

[
  {
    "id": "<string>",
    "state": "staged",
    "manager_id": "<string>",
    "is_manager": true,
    "first_name": "<string>",
    "last_name": "<string>",
    "full_name": "<string>",
    "email": "<string>",
    "username": "<string>",
    "badge_id": "<string>",
    "employee_id": "<string>",
    "employee_alt_id": "<string>",
    "timestamp": {
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "deleted_at": "2023-11-07T05:31:56Z",
      "expires_at": "2023-11-07T05:31:56Z",
      "provisioned_at": "2023-11-07T05:31:56Z",
      "deprovisioned_at": "2023-11-07T05:31:56Z"
    },
    "org": {},
    "metadata": {},
    "count": {
      "secondary_users": 123,
      "direct_report_users": 123,
      "directory_identities": 123,
      "policy_conditions": 123,
      "policy_users": 123,
      "policy_rulesets": 123,
      "manifest_rules": 123,
      "qualified_rules": 123,
      "staged_rules": 123,
      "workspace_logs_parent": 123,
      "workspace_logs_record": 123,
      "workspace_logs_related": 123,
      "workspace_logs_subject": 123,
      "directory_attributes": 123,
      "gitlab_groups": 123,
      "gitlab_projects": 123,
      "google_drive_docs": 123,
      "google_drive_files": 123,
      "google_drive_folders": 123,
      "google_drive_decks": 123,
      "google_drive_sheets": 123,
      "google_identity_groups": 123,
      "google_workspace_drives": 123,
      "google_workspace_groups": 123,
      "okta_groups": 123,
      "slack_public_channels": 123,
      "slack_private_channels": 123,
      "slack_groups": 123
    },
    "included": {
      "manager_user": {
        "id": "<string>",
        "state": "staged",
        "manager_id": "<string>",
        "is_manager": true,
        "full_name": "<string>",
        "email": "<string>",
        "username": "<string>",
        "org": {},
        "metadata": {}
      },
      "workspace_user": {
        "id": "<string>",
        "state": "staged",
        "provider": "google",
        "provider_id": "<string>",
        "name": "<string>",
        "handle": "<string>",
        "email": "<string>"
      },
      "parent_user": {
        "id": "<string>",
        "state": "staged",
        "manager_id": "<string>",
        "is_manager": true,
        "full_name": "<string>",
        "email": "<string>",
        "username": "<string>",
        "org": {},
        "metadata": {}
      },
      "secondary_users": {
        "id": "<string>",
        "state": "staged",
        "manager_id": "<string>",
        "is_manager": true,
        "full_name": "<string>",
        "email": "<string>",
        "username": "<string>",
        "org": {},
        "metadata": {}
      },
      "direct_report_users": [
        {
          "id": "<string>",
          "state": "staged",
          "manager_id": "<string>",
          "is_manager": true,
          "full_name": "<string>",
          "email": "<string>",
          "username": "<string>",
          "org": {},
          "metadata": {}
        }
      ],
      "workspace_integration": {
        "id": "<string>",
        "is_primary": true,
        "vendor": "demo",
        "handle": "<string>",
        "domain": "<string>"
      },
      "directory_identities": [
        {
          "id": "<string>",
          "workspace_integration_id": "<string>",
          "directory_user_id": "<string>",
          "integration_vendor": "demo",
          "integration_handle": "<string>",
          "vendor_id": "<string>",
          "full_name": "<string>",
          "email": "<string>",
          "org": {},
          "state": "staged"
        }
      ],
      "policy_conditions": [
        {
          "id": "<string>",
          "is_imported": true,
          "type": "attribute",
          "ruleset_id": "<string>",
          "rule_id": "<string>",
          "resource_id": "<string>",
          "profile_key": "<string>",
          "profile_operator": "equals",
          "profile_value": "<string>",
          "description": "<string>"
        }
      ],
      "policy_users": [
        {
          "id": "<string>",
          "state": "staged",
          "timestamp": {
            "created_at": "2023-11-07T05:31:56Z",
            "updated_at": "2023-11-07T05:31:56Z",
            "activated_at": "2023-11-07T05:31:56Z",
            "expires_at": "2023-11-07T05:31:56Z",
            "deleted_at": "2023-11-07T05:31:56Z"
          },
          "included": {
            "directory_user": {
              "id": "<string>",
              "state": "staged",
              "manager_id": "<string>",
              "is_manager": true,
              "full_name": "<string>",
              "email": "<string>",
              "username": "<string>",
              "org": {},
              "metadata": {}
            },
            "policy_ruleset": {
              "id": "<string>",
              "state": "unmanaged",
              "type": "directory_attribute",
              "resource_id": "<string>",
              "is_authoritative": true,
              "expires_after_days": 123
            },
            "policy_rule": {
              "id": "<string>",
              "state": "staged",
              "role_name": "<string>",
              "role_handle": "<string>",
              "is_imported": true,
              "description": "<string>",
              "expires_after_days": 123,
              "expires_after_days_inherited": true,
              "priority": 123
            }
          }
        }
      ],
      "policy_rules_manifest": [
        {
          "id": "<string>",
          "state": "staged",
          "role_name": "<string>",
          "role_handle": "<string>",
          "is_imported": true,
          "description": "<string>",
          "expires_after_days": 123,
          "expires_after_days_inherited": true,
          "priority": 123
        }
      ],
      "policy_rules_qualified": [
        {
          "id": "<string>",
          "state": "staged",
          "role_name": "<string>",
          "role_handle": "<string>",
          "is_imported": true,
          "description": "<string>",
          "expires_after_days": 123,
          "expires_after_days_inherited": true,
          "priority": 123
        }
      ],
      "policy_rules_staged": [
        {
          "id": "<string>",
          "state": "staged",
          "role_name": "<string>",
          "role_handle": "<string>",
          "is_imported": true,
          "description": "<string>",
          "expires_after_days": 123,
          "expires_after_days_inherited": true,
          "priority": 123
        }
      ],
      "policy_rulesets": [
        {
          "id": "<string>",
          "state": "unmanaged",
          "type": "directory_attribute",
          "resource_id": "<string>",
          "is_authoritative": true,
          "expires_after_days": 123
        }
      ]
    },
    "links": {
      "self": "<string>",
      "workspace_user": "<string>",
      "workspace_integration": "<string>",
      "secondary_users": "<string>",
      "direct_report_users": "<string>",
      "directory_identities": "<string>",
      "workspace_logs_parent": "<string>",
      "workspace_logs_record": "<string>",
      "workspace_logs_related": "<string>",
      "workspace_logs_subject": "<string>"
    }
  }
]

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

include · string

Available includes are manager-user, manager-user-count, manager-user-exists, workspace-user, workspace-user-count, workspace-user-exists, parent-user, parent-user-count, parent-user-exists, secondary-users, secondary-users-count, secondary-users-exists, direct-report-users, direct-report-users-count, direct-report-users-exists, workspace-integration, workspace-integration-count, workspace-integration-exists, directory-identities, directory-identities-count, directory-identities-exists, policy-conditions, policy-conditions-count, policy-conditions-exists, policy-users, policy-users-count, policy-users-exists, policy-rules-manifest, policy-rules-manifest-count, policy-rules-manifest-exists, policy-rules-qualified, policy-rules-qualified-count, policy-rules-qualified-exists, policy-rules-staged, policy-rules-staged-count, policy-rules-staged-exists, policy-rulesets, policy-rulesets-count, policy-rulesets-exists. You can include multiple options by separating them with a comma.

filter[id] · string

Filter by an exact ID match.

Example:

"drusr_01hq8xyzabc123def456ghi789"

filter[id_search] · string

Filter by a partial ID match.

Example:

"d662"

filter[workspace_integration_id] · string

Filter by the associated workspace integration ID.

Example:

"wsitg_01hq8xyzabc123def456ghi789"

filter[parent_id] · string

For secondary users, you can filter by the parent user ID.

Example:

"drusr_01hq8xyzabc123def456ghi789"

filter[manager_id] · string

Filter by users that report to a specific manager user ID.

Example:

"drusr_01hq8xyzabc123def456ghi789"

filter[first_name] · string

Filter by the first (given) name of the user (exact match).

Example:

"Dade"

filter[first_name_search] · string

Filter by the first (given) name of the user (partial match).

Example:

"Dad"

filter[last_name] · string

Filter by the last (family) name of the user (exact match).

Example:

"Murphy"

filter[last_name_search] · string

Filter by the last (family) name of the user (partial match).

Example:

"Mur"

filter[full_name] · string

Filter by the full (first and last) name of the user (exact match).

Example:

"Dade Murphy"

filter[full_name_search] · string

Filter by the full (first and last) name of the user (partial match).

Example:

"Dade"

filter[email] · string

Filter by the email address of the user (exact match).

Example:

"[e-mail]"

filter[email_search] · string

Filter by the email address of the user (partial match). This is useful for searching by email handle or domain name.

Example:

"dmurphy"

filter[username] · string

Filter by the username of the user (exact match).

Example:

"dade.murphy"

filter[username_search] · string

Filter by the username of the user (partial match).

Example:

"z3r0c00l"

filter[badge_id] · string

Filter by the badge ID number of the user (exact match).

Example:

"a1b2c3d4e5"

filter[badge_id_search] · string

Filter by the badge ID number of the user (partial match).

Example:

"a1b2c"

filter[employee_id] · string

Filter by the employee ID number of the user (exact match).

Example:

"a1b2c3d4e5"

filter[employee_id_search] · string

Filter by the employee ID number of the user (partial match).

Example:

"a1b2c"

filter[employee_alt_id] · string

Filter by the alternate employee ID number of the user (exact match).

Example:

"a1b2c3d4e5"

filter[employee_alt_id_search] · string

Filter by the alternate employee ID number of the user (partial match).

Example:

"a1b2c"

filter[org_array_search] · string

Search organization metadata key/value pairs for any partial string. For more granularity and specific keys, use the Policy Users endpoint for a specific Directory Dimension or Attribute.

Example:

"Engineer"

filter[metadata_array_search] · string

Search custom organization business logic metadata key/value pairs for any partial string.

filter[manager] · boolean

Filter users that are managers (have direct reports) or are not managers (individual contributors).

filter[state] · string

The state of the Directory User. See the Response Body below for more details on each state type.

Example:

"active"

filter[created_before] · string<date>

Filter results by date. Any parsable date format can be used.

Example:

"2025-01-01 or 2025-01-01 12:30:00 or 2025-01-01T12:30:00Z"

filter[created_after] · string<date>

Filter results by date. Any parsable date format can be used.

Example:

"2025-01-01 or 2025-01-01 12:30:00 or 2025-01-01T12:30:00Z"

filter[updated_before] · string<date>

Filter results by date. Any parsable date format can be used.

Example:

"2025-01-01 or 2025-01-01 12:30:00 or 2025-01-01T12:30:00Z"

filter[updated_after] · string<date>

Filter results by date. Any parsable date format can be used.

Example:

"2025-01-01 or 2025-01-01 12:30:00 or 2025-01-01T12:30:00Z"

filter[expires_before] · string<date>

Filter results by date. Any parsable date format can be used.

Example:

"2025-01-01 or 2025-01-01 12:30:00 or 2025-01-01T12:30:00Z"

filter[expires_after] · string<date>

Filter results by date. Any parsable date format can be used.

Example:

"2025-01-01 or 2025-01-01 12:30:00 or 2025-01-01T12:30:00Z"

filter[expired_before] · string<date>

Filter results by date. Any parsable date format can be used.

Example:

"2025-01-01 or 2025-01-01 12:30:00 or 2025-01-01T12:30:00Z"

filter[expired_after] · string<date>

Filter results by date. Any parsable date format can be used.

Example:

"2025-01-01 or 2025-01-01 12:30:00 or 2025-01-01T12:30:00Z"

filter[deactivated_before] · string<date>

Filter results by date. Any parsable date format can be used.

Example:

"2025-01-01 or 2025-01-01 12:30:00 or 2025-01-01T12:30:00Z"

filter[deactivated_after] · string<date>

Filter results by date. Any parsable date format can be used.

Example:

"2025-01-01 or 2025-01-01 12:30:00 or 2025-01-01T12:30:00Z"

filter[deleted_before] · string<date>

Filter results by date. Any parsable date format can be used.

Example:

"2025-01-01 or 2025-01-01 12:30:00 or 2025-01-01T12:30:00Z"

filter[deleted_after] · string<date>

Filter results by date. Any parsable date format can be used.

Example:

"2025-01-01 or 2025-01-01 12:30:00 or 2025-01-01T12:30:00Z"

filter[provisioned_before] · string<date>

Filter results by date. Any parsable date format can be used.

Example:

"2025-01-01 or 2025-01-01 12:30:00 or 2025-01-01T12:30:00Z"

filter[provisioned_after] · string<date>

Filter results by date. Any parsable date format can be used.

Example:

"2025-01-01 or 2025-01-01 12:30:00 or 2025-01-01T12:30:00Z"

filter[deprovisioned_pending_deactivation] · string<boolean>

Get all active records that have been deprovisioned by the integration vendor

Example:

true

filter[deprovisioned_before] · string<date>

Filter results by date. Any parsable date format can be used.

Example:

"2025-01-01 or 2025-01-01 12:30:00 or 2025-01-01T12:30:00Z"

filter[deprovisioned_after] · string<date>

Filter results by date. Any parsable date format can be used.

Example:

"2025-01-01 or 2025-01-01 12:30:00 or 2025-01-01T12:30:00Z"

filter[trashed] · string

Can be a value of with (response will contain deleted items as well), only (will contain only deleted items), or any arbitrary value (will contain only not deleted items).

filter · string

page · string

sort · string

Response

200

application/json

The collection of DirectoryUserDetailedResponseData

id · string · required

Example:

"drusr_01hq8xyzabc123def456ghi789"

state · enum<string> · required

The state of the directory user

staged The record is staged and is only visible to administrators or in the API. Since Directory Users are managed by Directory Identities with your primary integration, this usually indicates that the user is staged and will be activated or onboarded soon. Staged users are not included in ruleset manifests until they are active users.
active The record is active.
expiring The expires_at value is set in the future for the record. You can run the activate action to remove the scheduled expiration.
expired The expires_at value is in the past and the record was deactivated.
suspended The record is temporarily suspended. This reflects the state of the primary Workspace Integration.
deactivated The record was deactivated in the primary Workspace Integration.

Available options: staged, active, expiring, expired, suspended, deactivated

Example:

"active"

manager_id · string | null · required

The ID of the manager

Example:

"drusr_01kam9z5z71f7r4hhrm2ydxkhn"

is_manager · boolean · required

Whether or not the user is a people manager with direct reports

Example:

true

first_name · string · required

The first (given) name of the user

Example:

"Dade"

last_name · string · required

The last (family) name of the user

Example:

"Murphy"

full_name · string · required

The first and last name of the user

Example:

"Dade Murphy"

email · string · required

The email address of the user

Example:

"[e-mail]"

username · string · required

The username of the user. Unless overridden, this is usually the email address handle

Example:

"dmurphy"

badge_id · string | null · required

The badge ID number of the user. This value is dynamically obtained from the primary integration based on the badge_id_profile_key

employee_id · string | null · required

The employee ID number of the user. This value is dynamically obtained from the primary integration based on the employee_id_profile_key

employee_alt_id · string | null · required

An alternative/secondary employee ID number of the user. This value is dynamically obtained from the primary integration based on the employee_alt_id_profile_key

timestamp · DirectoryUserTimestampResponseData · object · required

The timestamps for the directory user record

Show child attributes

org · object · required

The user's organization metadata based on their dimension attributes

Show child attributes

Example:

{
  "cost_center": "CC-1234",
  "department": "Infrastructure",
  "division": "Engineering",
  "title": "Senior Engineer"
}

metadata · object · required

The user's custom key/value metadata added by someone or automation in your organization

Show child attributes

Example:

{
  "custom_field_1": "value1",
  "employee_type": "full-time",
  "desk_number": "42"
}

count · DirectoryUserCountResponseData · object · required

Counts of related resources for the directory user

Show child attributes

included · DirectoryUserIncludedResponseData · object · required

Related resources for the directory user. Use include parameter with a comma separated list of resources to fetch related data

Show child attributes

links · DirectoryUserLinkResponseData · object · required

API hyperlinks related to the directory user record

Show child attributes