Skip to content

Users

API URLs

  • Testing: https://gql-users-external.staging.xoeye.com/graphql
  • Production: https://gql-users-external.xoi.io/graphql

Getting a List of Users

Example Request

The following request will get a list of Users from within your Organization in Vision. The limit here is set to 1, but you can change that to see more results.

See the ListUsersInput schema for the details of what is required for this request.

query {
  listUsers(input: { limit: 1, nextToken: "" }) {
    userConnection {
      items {
        id
        given_name
        family_name
      }
      nextToken
    }
  }
}

Example Response

As with all queries where a nextToken can be used, if you get a non-empty nextToken in this response, you can plug it into the listUsers request you just made. That will return you the next subset of results.

See the ListUsersResult schema for the details of what to expect in your response.

{
  "data": {
    "listUsers": {
      "userConnection": {
        "items": [
          {
            "id": "a-user-id",
            "given_name": "First",
            "family_name": "Last"
          }
        ],
        "nextToken": "eyJvcmdJRCI6ICJYT2"
      }
    }
  }
}

Getting a Single User by ID

When sending the listUsers query discussed above, we opted to have the id returned. We can now use that id to retrieve a specific User.

Note:

  • You are not required to call listUsers prior to getUser. You can and should store user ids for retrieving users in the future.
  • For historical reasons, the id that you see for a user in your organization may look like an email address. Do not rely on this to be the case. If you need the email address for a user, be sure to use the email field, as we may choose to switch to GUIDs in the future.
  • We will NOT change the id of any existing user should we switch to GUIDs.

Example Request

See the GetUserInput schema for the details of what is required for this request.

query {
  getUser(input: { id: "a-user-id" }) {
    user {
      email
      given_name
      family_name
    }
  }
}

Example Response

See the GetUserResult schema for the details of what to expect in your response.

{
  "data": {
    "getUser": {
      "user": {
        "email": "First.Last@organization.com",
        "given_name": "First",
        "family_name": "Last"
      }
    }
  }
}

Getting Users by Email Address

There may be times when you haven't yet stored the Vision ID for one of your users, and you need to get the ID for use with other requests. In those cases, you can use getUsersByEmail. Given an email address, this query will return any users in your organization with that email address. Since we're still using email address as the ID, this will currently return a single-item array. Once we've decoupled those two ideas, this may be able to return multiple users that share an email address.

Note:

  • You should store the ID for each of your users so that you can reference their Vision user records directly without needing this call.
  • This is a case insensitive call, so if you send it to us as Someone@yourcompany.com or SomeOne@yourcompany.com the same user will be returned

Example Request

See the GetUsersByEmailInput schema for the details of what is required for this request.

query {
  getUsersByEmail(input: { email: "someone@yourcompany.com" }) {
    users {
      id
      given_name
      family_name
    }
  }
}

Example Response

See the GetUsersByEmailResult schema for the details of what to expect in your response.

{
  "data": {
    "getUsersByEmail": {
      "users": [
        {
          "id": "someone@yourcompany.com",
          "given_name": "someone"
        }
      ]
    }
  }
}

Getting Groups

It is possible to retrieve information regarding groups of Vision users, including the membership of these groups. This can be useful if you wish to use membership in a given Vision group as a determining factor for some behavior in an integration. For example, using membership in a "beta testers" group in Vision might be used to limit which users receive new jobs.

Notes:

  • Currently, a group's id can be determined from within Vision Web by editing the group and referencing the URL. The final path sement constitutes the group ID and is distinct from the group name as it will include your orgs ID. For example, a group named A Group might have an id of your-org-a-group, and will appear in that URL as ...oups/edit/your-org-a-group
  • As noted above, for historical reasons, the user ids referenced in the members list may look like an email address. Do not rely on this to be the case, as we may choose to switch to GUIDs in the future. These values will match the id of users in Vision. If, however, we do make that change, we will NOT change the id of any existing user.
  • Groups that do not exist will not be present in the response, but no error will be returned. This allows for graceful handling of group removal.

Example Request

See the GetGroups schema for the details of what is required for this request.

query {
  getGroups(
    input: { ids: ["your-org-a-group", "your-org-nonexistent-group"] }
  ) {
    groups {
      id
      name
      description
      members
    }
  }
}

Example Response

See the GetGroupsResult schema for the details of what to expect in your response.

{
  "data": {
    "getGroups": {
      "groups": [
        {
          "id": "your-org-a-group",
          "name": "A Group",
          "description": "",
          "members": ["tech@example.com"]
        }
      ]
    }
  }
}