Users (API v2) – App47, Inc.

Introduction

This article will explain how to manage your users on the App47 portal.

App47 APIv2 Users

The Users end point allows you create, update, list, view, and delete users in your account. You must have the proper permissions in your account in order to use this end point with your member token.

To use this API you must have the following permissions:

Action	Required permission
List users	At least read permission
Search user	At least read permission or have “Purchase Permission” set to true
Show user	At least read permission
Edit user	At least edit permission
Create User	Manage permission
Delete User	Manage permission

For more information on how to configure your APIv2 calls, please consult the APIv2 Overview.

Parameters (with options)

When fetching, creating or updating information about users, the following parameters are available through the API:

Parameter Name	Input	Input Format	Output	Description
name	Yes	Any string	Yes	Name of the user
email	Yes	Any email string	Yes	Email address for the user
ui_version	Yes	"1" "2" "3"	Yes	UI version of the user's app store
message_for_invitation	Yes	Any string	Yes	Message for the user to be included when inviting them to the app store
active	Yes	"yes" "no"	Yes	If this user is active
require_passphrase	Yes	"yes" "no"	Yes	If this user requires a passphrase
default_passphrase_expiration	Yes	"24" "48" "120" "168" "240" "336"	Yes	Default passphrase expiration for the user. Input is in hours
marketing_opt_out	Yes	"yes" "no"	Yes	If this user should be opted out of marketing emails

List Users

In order to list users in your account, you have at least read access.

End Point

GET https://cirrus.app47.com/api/v2/users

Example:

curl -H"Access-Token: <<your token>>"  https://cirrus.app47.com/api/v2/users

Input Parameters

Parameter	Description	Required?	Example(s)/Allowed Values
search_term	Search phrase to filter the user list	No	Any text
skip	The number of records to skip over	No	Integer greater than zero

Example: To list only users with the name or email “joe” in them:

curl -H"Access-Token: <<your token>>"  https://webui.app47.net/api/v2/users?search_term=joe

Expected Output

If valid, it will return a result with:

Success set to true
Skip - the number of records that were skipped (The API will return sets of 100 records)
Total - The total number of records in your account
Count - The total number of records returned in this response
List - List of users you have access to and match the input parameters
A md5 hash of the results element
HTTP result code 200

{
  "results":
    {
      "skip": 0,
      "total": 0,
      "count": 0,
      "list": [],
      "success":true
    },
  "md5":"896d94e5e2f4eb6b6bfa19144c7794e5"
}

If invalid, it will return a result with:

Success set to false
A message indicating the error
A md5 has of the results element
HTTP result code that is *not* 200

{
  "results":
    {
      "message":"Access denied",
      "success":false
    },
  "md5":"896d94e5e2f4eb6b6bfa19144c7794e5"
}

Show a Specific User

Showing a specific user in your account is done by User ID. The User ID can be found on the previous call to list all users.

End Point

GET https://cirrus.app47.com/api/v2/users/«user_id»

Example:

curl -H"Access-Token: <<your token>>"  https://cirrus.app47.com/api/v2/users/<< user_id >>

Input Parameters

Parameter	Description	Required?	Example(s)/Allowed Values
user_id	The ID of the User	Yes	A valid user id in your account that you have permission to view

Expected Output

{
  "results":
    {
      "user":
        {
          "id":"544fa14538d6b81f6b00003d",
          "created":"2014-10-28T13:59:34Z",
          "modified":"2015-08-03T15:43:35Z",
          "name":"Joe Smith",
          "email":"joe@abc.com",
          "active":true,
          "invite_sent":"2015-08-03T15:43:35Z",
          "require_passphrase":true,
          "default_passphrase_expiration":48,
          "marketing_opt_out": false
        },
      "success":true
    },
  "md5":"7232f70a2678e2b4ba959fd853488ab1"
}

Search for a Specific User by Email Address

Show a specific user in your account by email address, pattern matching is not allowed.

End Point

GET https://cirrus.app47.com/api/v2/users/search?email=joe%40abc.com

Example:

curl -H"Access-Token: <<your token>>"  https://cirrus.app47.com/api/v2/users/search?email=joe%40abc.com

Input Parameters

Parameter	Description	Required?	Example(s)/Allowed Values
email	The email address of the user	Yes	A valid email address for a user

Expected Output

{
  "results":
    {
      "user":
        {
          "id":"544fa14538d6b81f6b00003d",
          "created":"2014-10-28T13:59:34Z",
          "modified":"2015-08-03T15:43:35Z",
          "name":"Joe Smith",
          "email":"joe@abc.com",
          "active":true,
          "invite_sent":"2015-08-03T15:43:35Z",
          "require_passphrase":true,
          "default_passphrase_expiration":48,
          "marketing_opt_out": false
        },
      "success":true
    },
  "md5":"7232f70a2678e2b4ba959fd853488ab1"
}

Update a User

Updating a specific user in your account is done by user ID. The user ID can be found on the previous call to list all users.

Parameters that are allowed during update can be found in the table above where the Input column contains a Yes.

End Point

PUT https://cirrus.app47.com/api/v2/users/«user_id»

Example:

curl -X PUT -H"Access-Token: <<your token>>" -H"Content-Type: application/json" -d '{"user": { "name": "Updated Name" } }'  https://cirrus.app47.com/api/v2/user/<< user_id >>

Expected Output

{
  "results":
    {
      "user":
        {
          "id":"544fa14538d6b81f6b00003d",
          "created":"2014-10-28T13:59:34Z",
          "modified":"2015-08-03T15:43:35Z",
          "name":"Joe Smith",
          "email":"joe@abc.com",
          "active":true,
          "invite_sent":"2015-08-03T15:43:35Z",
          "require_passphrase":true,
          "default_passphrase_expiration":48,
          "marketing_opt_out": false
        },
      "success":true
    },
  "md5":"7232f70a2678e2b4ba959fd853488ab1"
}

Create a User

You may only create user if your member has the permission to manage users.

Parameters that are allowed during creation can be found in the table above where the Input column contains a Yes in the row.

End Point

POST https://cirrus.app47.com/api/v2/users

Example:

curl -X POST -H"Access-Token: <<your token>>" -H "Content-Type: application/json" -d '{"user": { "name": "New Name", "email": "new@abc.com" } }'  https://cirrus.app47.com/api/v2/users

Expected Output

{
  "results":
    {
       "user":
        {
          "id":"544fa14538d6b81f6b00003d",
          "created":"2014-10-28T13:59:34Z",
          "modified":"2015-08-03T15:43:35Z",
          "name":"New Name",
          "email":"new@abc.com",
          "active":true,
          "invite_sent":"2015-08-03T15:43:35Z",
          "require_passphrase":true,
          "default_passphrase_expiration":48,
          "marketing_opt_out": false
        },
      "success":true
    },
  "md5":"7232f70a2678e2b4ba959fd853488ab1"
}

Create a User with More Parameters

You may only create user if your member has the permission to manage users.

Parameters that are allowed during creation can be found in the table above where the Input column contains a Yes in the row.

End Point

POST https://cirrus.app47.com/api/v2/users

Setting the ui_version option

Example:

curl -X POST -H"Access-Token: <<your token>>" -H"Content-Type: application/json" -d '{"user": { "name": "New Name", "email": "new@abc.com", "ui_version": "2" } }' https://cirrus.app47.com/api/v2/users

Expected Output

{
  "results":
    {
      "user":
      {
         "id":"5f0c85acb897b2653c3d0860",
         "created":"2020-07-13T16:02:52.483Z",
         "modified":"2020-07-13T16:02:52.483Z",
         "name":"New Name",
         "email":"new@abc.com",
         "email_bounced_at":"Unknown",
         "email_bounce_reason":null,
         "message_for_invitation":null,
         "active":true,
         "invite_sent":false,
         "ui_version":2,
         "require_passphrase":false,
         "default_passphrase_expiration":48,
         "marketing_opt_out":false
        },
      "success":true
    },
  "md5":"29091e0bb39d8c4d1e5055a7090d5073"
}

Setting the require_passphrase option

Example:

curl -X POST -H"Access-Token: <<your token>>" -H"Content-Type: application/json" -d '{"user": { "name": "New Name", "email": "new@abc.com", "require_passphrase": "yes" } }' https://cirrus.app47.com/api/v2/users

Expected Output

{
  "results":
    {
      "user":
      {
         "id":"5f0c85acb897b2653c3d0860",
         "created":"2020-07-13T16:02:52.483Z",
         "modified":"2020-07-13T16:02:52.483Z",
         "name":"New Name",
         "email":"new@abc.com",
         "email_bounced_at":"Unknown",
         "email_bounce_reason":null,
         "message_for_invitation":null,
         "active":true,
         "invite_sent":false,
         "ui_version":2,
         "require_passphrase":true,
         "default_passphrase_expiration":48,
         "marketing_opt_out":false
        },
      "success":true
    },
  "md5":"29091e0bb39d8c4d1e5055a7090d5073"
}

Setting the default_passphrase_expiration option (must also set require_passphrase)

Note: default_passphrase_expiration must be equal to the hours the passphrase lasts, and must be one of the following:

Example:

curl -X POST -H"Access-Token: <<your token>>" -H"Content-Type: application/json" -d '{"user": { "name": "New Name", "email": "new@abc.com", "require_passphrase": "yes" "default_passphrase_expiration": "48" } }' https://cirrus.app47.com/api/v2/users

Expected Output

{
  "results":
    {
      "user":
      {
         "id":"5f0c85acb897b2653c3d0860",
         "created":"2020-07-13T16:02:52.483Z",
         "modified":"2020-07-13T16:02:52.483Z",
         "name":"New Name",
         "email":"new@abc.com",
         "email_bounced_at":"Unknown",
         "email_bounce_reason":null,
         "message_for_invitation":null,
         "active":true,
         "invite_sent":false,
         "ui_version":2,
         "require_passphrase":true,
         "default_passphrase_expiration":48,
         "marketing_opt_out":false
        },
      "success":true
    },
  "md5":"29091e0bb39d8c4d1e5055a7090d5073"
}

Delete a User

You may only delete users if you can manage users.

End Point

DELETE https://cirrus.app47.com/api/v2/users/«user_id»

Example:

curl -X DELETE -H"Access-Token: <<your token>>"  https://cirrus.app47.com/api/v2/users/<<user_id>>

Expected Output

{
  "results":
    {
      "message":"User was deleted",
      "success":true
    },
  "md5":"f3d0a22e47ce6158551f483e07b16fe1"
}