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.