Users

The Users API provides a simple interface to your account's users. The API provides read-only access, where you can retrieve a single user as well as list of all users associated with your account.

When you sign up with Sell, we create a single master account and a single user with account management privileges. By logging in as the account manager, you can create as many additional users as you need.

JSON format

Name	Read Only	Type	Description
id	true	number	Unique identifier of the user.
name	false	string	Full name of the user.
email	false	string	Email address of the user.
status	true	string	Status of the user's account. Usually active. Possible values: active, inactive
invited	true	boolean	Indicates whether an invitation has been sent to the user or not. Usually true.
confirmed	true	boolean	Indicates whether the user's account has been confirmed or not.
phone_number	false	string	Contact phone number of the user.
role	true	string	Role of the user. Notice that this attribute has no connection with role based access control and permissions. It indicates whether the user is an admin or a regular user. Possible values: user, admin
roles	false	array	An array of roles assigned to the user. Each entry in the array includes a unique identifier of the role and it's name. You can expect unique values in the array. RBAC API is not yet public.
team_name	true	string	Name of the team the user belongs to.
group	true	object	Group the user belongs to. The group entry includes a unique identifier and a name.
reports_to	true	number	Unique identifier of the manager of the user.
timezone	false	string	Timezone of the user as the offset from Coordinated Universal Time (UTC) in the format `UTC(+
created_at	true	string	Date and time of creation in UTC (ISO8601 format).
updated_at	true	string	Date and time of the last update in UTC (ISO8601 format).
deleted_at	true	string	Date and time of deletion in UTC (ISO8601 format) in case the user has been deleted.
zendesk_user_id	true	string	If your Sell account is linked to a Zendesk account, the user will have a Zendesk user ID.
identity_type	false	string	The user can be either a person (an agent) or an integration (an internal system user). Possible values: person, integration

Retrieve all users

GET /v2/users

Returns all users, according to the parameters provided.

Parameters

Name	Required	Type	In	Description
page	false	number	Query	Page number to start from. Page numbering starts at 1, and omitting the page parameter will return the first page.
per_page	false	number	Query	Number of records to return per page. The default limit is 25, and the maximum number that can be returned is 100.
sort_by	false	string	Query	A field to sort by. The default order is ascending. If you want to change the sort order to descending, append :desc to the field e.g. sort_by=name:desc. Possible values: id, name, created_at, updated_at
ids	false	string	Query	Comma-separated list of user IDs to be returned in a request.
name	false	string	Query	Name of the user. This parameter is used in a strict sense.
email	false	string	Query	Email of the user. This parameter is used in a strict sense.
role	false	string	Query	Role of user to search for. Possible values: user, admin
role_id	false	number	Query	The unique identifier of the role.
status	false	string	Query	Status of user accounts to search for. Possible values: active, inactive
confirmed	false	boolean	Query	Indicator whether to return only confirmed user accounts or not.
zendesk_user_ids	false	string	Query	Comma-separated list of Zendesk user IDs. If your Sell account is linked to a Zendesk account, the user will have a Zendesk user ID.
identity_type	false	string	Query	The user can be either a person (an agent) or an integration (an internal system user). Possible values: person, integration

Allowed for

• Agents

Using cURL

curl -v -X GET https://api.getbase.com/v2/users?role=user&status=active&confirmed=true \
-H "Accept: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN"

Example response

HTTP/1.1 200 OK

Content-Type: application/json; charset=utf-8
Content-Language: en

{
  "items": [
    {
      "data": {
        "id": 2,
        "name": "Mark Johnson",
        "email": "[email protected]",
        "status": "active",
        "invited": true,
        "confirmed": true,
        "role": "user",
        "created_at": "2014-08-27T16:32:56Z",
        "updated_at": "2014-08-27T17:32:56Z",
        "deleted_at": null,
        "roles": [
          {
            "id": 1,
            "name": "Closer"
          }
        ],
        "phone_number": "508-778-6516",
        "timezone": "UTC-05:00",
        "reports_to": 1,
        "team_name": "Mark Johnson's Team",
        "group": {
          "id": 1,
          "name": "Closers A Group"
        }
      },
      "meta": {
        "type": "user"
      }
    }
  ],
  "meta": {
    "type": "collection",
    "count": 1,
    "links": {
      "self": "http://api.getbase.com/v2/users.json"
    }
  }
}

---

Retrieve a single user

GET /v2/users/:id

Returns a single user according to the unique user ID provided. If the specified user does not exist, this query returns an error.

Parameters

Name	Required	Type	In	Description
id	true	number	Query	Unique identifier of the user.

Allowed for

• Agents

Using cURL

curl -v -X GET https://api.getbase.com/v2/users/2 \
-H "Accept: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN"

Example response

HTTP/1.1 200 OK

Content-Type: application/json; charset=utf-8
Content-Language: en

{
  "data": {
    "id": 2,
    "name": "Mark Johnson",
    "email": "[email protected]",
    "status": "active",
    "invited": true,
    "confirmed": true,
    "role": "user",
    "created_at": "2014-08-27T16:32:56Z",
    "updated_at": "2014-08-27T17:32:56Z",
    "deleted_at": null,
    "roles": [
      {
        "id": 1,
        "name": "Closer"
      }
    ],
    "phone_number": "508-778-6516",
    "timezone": "UTC-05:00",
    "reports_to": 1,
    "team_name": "Mark Johnson's Team",
    "group": {
      "id": 1,
      "name": "Closers A Group"
    }
  },
  "meta": {
    "type": "user"
  }
}

---

Retrieve an authenticating user

GET /v2/users/self

Returns a single authenticating user, according to the authentication credentials provided.

Allowed for

• Agents

Using cURL

curl -v -X GET https://api.getbase.com/v2/users/self \
-H "Accept: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN"

Example response

HTTP/1.1 200 OK

Content-Type: application/json; charset=utf-8
Content-Language: en

{
  "data": {
    "id": 2,
    "name": "Mark Johnson",
    "email": "[email protected]",
    "status": "active",
    "invited": true,
    "confirmed": true,
    "role": "user",
    "created_at": "2014-08-27T16:32:56Z",
    "updated_at": "2014-08-27T17:32:56Z",
    "deleted_at": null,
    "roles": [
      {
        "id": 1,
        "name": "Closer"
      }
    ],
    "phone_number": "508-778-6516",
    "timezone": "UTC-05:00",
    "reports_to": 1,
    "team_name": "Mark Johnson's Team",
    "group": {
      "id": 1,
      "name": "Closers A Group"
    }
  },
  "meta": {
    "type": "user"
  }
}

---