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-8Content-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-8Content-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-8Content-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"  }}