Users

The /users resource allows access to user settings for the current user (used to authenticate), as well as sub-users, provided the user used to authenticate has the Admin role.

Listing all users

Request

GET /users

Arguments

Argument Type Description
count Number How many users to include in each page of results
page Number The page to retrieve

Response

A list of users, including metadata for each user. You’ll find more details about what’s available for every User below.

Example Response

// GET /users

GET /users?count=10&page=1
{
  "metadata": {
    "resultset": {
      "count": 10,
      "page": 1,
      "total_count": 17,
      "total_pages": 2
    }
  },
  "results": [
    {
      "active": true,
      "currency": "USD",
      "region": "us",
      "is_owner": false,
      "share_of_profit": "1.00",
      "last_login": "2021-12-21T11:12:13",
      "timezone": "Eastern Standard Time",
      "account": {
        "id": 12345678,
        "company": "Appfigures",
        "auto_import": true,
        "last_import": "2021-09-23T00:00:00",
        "plan": "Explore",
        "plan_id": 1,
        "is_premium": true
      },
      "id": 34567812,
      "role": "admin",
      "name": "John",
      "email": "john@smith.com",
      "products": null,
      "avatar_url": "https://secure.gravatar.com/avatar/...",
      "date_format": "MM/dd/yy",
      "entitlements": [
        "sales",
        "ads",
        "alerts",
        "toplists",
        "ranks",
        "reviews",
        "featured",
        "autoimport"
      ]
    },
    ...
  ]
}

Getting details for a user

Request

GET /users/{email or user_id}

Scope: This resource requires the account:read scope.

Arguments

Argument Type Description
email String The email address of the user to look up. Must be a member of your account.

Response

Field Type Description
active Bool (true|false) whether or not the user is active
currency String The user’s preferred currency. Also the currency all monetary reports will be reported in. Currencies can be found here.
region String (us|gb) The user’s preferred region for date and time format.
is_owner Bool (true | false) True if this user created the account, false otherwise.
last_login Date Date of the user’s last login to the site
timezone String The user’s preferred timezone. Also the timezone ranks reports will be reported in.
account Account An object representing the user’s account. See table below for details.
id Number The user’s Appfigures ID
role String The permission level of this user. Possible values are: viewer, admin. Some resources cannot be accessed by viewer users. Requests to those resources will result in a 403 Forbidden error.
name String The user’s full name
email String The user’s email address.
products List An array of products that this user has access to. Scroll down to the next method for more details about the product object.
date_format String A format to match the user’s region.

Account

Field Type Description
id String The account’s Appfigures ID
name String Account’s name
company String Account’s company name
auto_import String (true | false) whether or not the account supports autoimport
last_import String (legacy) We no longer report the account’s last import date in this API. This will always be the current date.
plan String The account’s plan: free, premium, publisher. Some resources cannot be accessed by users who are on the free plan. These resources will result in a 403 Forbidden error.

Example Response

// GET /users/john@fobsdirect.com

{
    "active": true,
    "currency": "USD",
    "region": "US",
    "is_owner": false,
    "share_of_profit": "1.00",
    "last_login": "2021-09-23T13:02:47",
    "timezone": "Eastern Standard Time",
    "account": {
        "id": 42,
        "company": "Smith's",
        "auto_import": "N/A",
        "last_import": "2021-09-23T00:00:00",
        "plan": "explore"
    },
    "id": 12345678,
    "role": "admin",
    "name": "John",
    "email": "john@smith.com",
    "date_format": "MM/dd/yy",
    "products": [
     ...
    ]
}

Changing a user’s status

Request

PUT /users/{user_id}

With the following JSON payload { "active": <true|false> }

Arguments

Argument Type Description
ID Number
Active Bool

Example

  // PUT /users/12345678

  {"active": false}

Response

If successful, this endpoint will respond with the full representation of the User that’s being updated.

Deleting a user

Request

DELETE /users/{user_id}

Arguments

Argument Type Description
user_id Number The ID of the user you’d like to delete.

Response

This endpoint will respond with a 204 No Content if the deletion was successful, or a 404 Not Found if the ID does not exist or is not a member of this account.

Note: User deletions cannot be undone. To temporarily disable a user change its status instead.