User Tools

Use the user tools to search users and retrieve support-oriented user context from the workspace bound to your API key.

Available tools

Tool	Purpose
user_list	List readable users in the current workspace.
user_count	Count readable users with optional filters.
user_find	Search users with optional status and group filters.
user_get_summary	Return the main operational summary for one user.
user_get_support_context	Return support-specific context for one user.

user_list

List readable users in the current workspace.

This tool does not take any parameters.

Response

{
  "items": [
    {
      "publicId": "usr_01hj5kq4k4a2v3x7p9m8n6c2dz",
      "email": "[e-mail]",
      "displayName": "John Doe",
      "status": "active",
      "group": "Sales"
    }
  ]
}

Notes

• The response is capped to the first 25 readable users.

• Only users with a concrete status are returned: active, inactive, hidden, or not_present.

• Returned items use the same compact user reference shape as user_find.

user_count

Count available users in the current workspace.

Parameters

Name	Type	Required	Description
query	String	No	Optional search query. Maximum length: 190.
status	String	No	One of active, inactive, hidden, not_present.
field	String	No	One of any, email, total. Default: any. total is accepted as a legacy alias for any.

Response

{
  "count": 128,
  "query": "john",
  "field": "email",
  "status": "active"
}

Notes

• When query is omitted or empty, query is returned as null.

• count only covers readable, non-deleted users with a non-null status in the workspace resolved from the API key.

user_find

Search users by free text. Results are limited to available users in the current workspace.

Parameters

Name	Type	Required	Description
query	String	Yes	Search query. Maximum length: 190.
status	String	No	One of active, inactive, hidden, not_present.
groupPublicId	String	No	Group public ID in grp_<lowercase_ulid> format.
limit	Integer	No	Result limit. Default: 10. Maximum: 10.

Response

{
  "items": [
    {
      "publicId": "usr_01hj5kq4k4a2v3x7p9m8n6c2dz",
      "email": "[e-mail]",
      "displayName": "John Doe",
      "status": "active",
      "group": "Sales"
    }
  ]
}

Notes

• Results only include readable, non-deleted users with a non-null status.

• groupPublicId must belong to a readable group in the current workspace.

user_get_summary

Return the main operational summary for a single user.

Parameters

Name	Type	Required	Description
userPublicId	String	Yes	User public ID in usr_<lowercase_ulid> format.

Response

{
  "publicId": "usr_01hj5kq4k4a2v3x7p9m8n6c2dz",
  "email": "[e-mail]",
  "displayName": "John Doe",
  "status": "active",
  "group": {
    "name": "Sales"
  },
  "workspace": {
    "name": "Acme"
  },
  "profile": {
    "identity": {
      "firstName": "John",
      "lastName": "Doe",
      "title": "Account Executive",
      "unit": "Revenue"
    },
    "contact": {
      "phone": "[phone]",
      "mobile": "[phone]",
      "secondEmail": "[e-mail]"
    },
    "address": {
      "streetAddr": "10 rue de Paris",
      "postalCode": "75001",
      "city": "Paris"
    },
    "formula": "Regards",
    "supplementaryLinks": {
      "calendar": "https://cal.example.com/john",
      "linkedin": "john-doe"
    },
    "extraFields": {
      "extra1": "Custom value"
    }
  },
  "connectors": {
    "tenant": "Microsoft 365",
    "sourceConnector": "azure",
    "enabledConnectors": [
      "desktop_app",
      "chrome_extension"
    ]
  }
}

Field notes

• workspace always describes the workspace resolved from the API key.

• group currently returns only the group name.

• profile is compacted server-side: empty sub-objects and empty values are omitted.

• formula is sanitized before being returned.

• enabledConnectors is a derived list and can contain values such as salesforce, pipedrive, smartlead, outreach, datananas, desktop_app, and chrome_extension.

• supplementaryLinks and extraFields can appear in the profile payload, but they are excluded from workspace completeness metrics.

user_get_support_context

Return support-focused information about licensing, activation, and connector state for one user.

Parameters

Name	Type	Required	Description
userPublicId	String	Yes	User public ID in usr_<lowercase_ulid> format.

Response

{
  "user": {
    "publicId": "usr_01hj5kq4k4a2v3x7p9m8n6c2dz",
    "email": "[e-mail]",
    "displayName": "John Doe",
    "status": "active",
    "group": "Sales"
  },
  "status": "active",
  "group": {
    "name": "Sales"
  },
  "license": {
    "hasLicense": true,
    "expiresAt": "2026-12-31T23:59:59+00:00"
  },
  "activation": {
    "desktopAppActivated": true,
    "vcardEnabled": true,
    "isAlias": false,
    "hasPhoto": true
  },
  "connectors": {
    "tenant": "Microsoft 365",
    "sourceConnector": "azure",
    "enabledConnectors": [
      "desktop_app",
      "chrome_extension"
    ]
  },
  "flags": {
    "hasGroup": true,
    "hasTenant": true,
    "hasSecondEmail": false,
    "hasLicense": true
  }
}

Field notes

• user merges the lightweight user reference with the compacted profile payload.

• license.hasLicense is the primary support flag for licensing.

• license.expiresAt is null when there is no expiration date.

• activation.isAlias is true for alias users.

• activation.desktopAppActivated is a boolean, not a timestamp.

• flags provides fast booleans for support workflows without extra client-side inference.