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 togetUser
. 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 theemail
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
orSomeOne@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 namedA Group
might have anid
ofyour-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 theid
of users in Vision. If, however, we do make that change, we will NOT change theid
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"]
}
]
}
}
}