Users API

Table of Contents
User Attributes
Get a List of Users
Get a Single User
Create a New User
Update an Existing User
Clear a user’s password failure lockout
Delete a User

User Attributes

id
integer
/
read-only

Internal identifier for this users.

full_name
string
/
required

Full name of this user.

Must be present and a maximum of 100 charaters in length.

email
string
/
required

Email address for this user.

Must be present and a valid email address.
Must be unique across the system.
Email addresses with international domain names are not supported.

active
boolean
/
required

True or false if this user can sign in.

role
string
/
required

Role of the user.

May be: system_admin, organization_admin, or standard
System administrators may only exist on the System Organization (ID = 1)

show_quick_tips
boolean
/
default: true

The user sees tips in the UI.

default_preview_recipients
array of strings

The email addresses that will be automatically filled in when sending preview emails.

Setting this field to null will clear to a blank array ([]).
May contain at most 100 email addresses.

terms_and_conditions_version
integer

The Terms & Conditions version number to which this user has agreed. A value of null indicates either the user has not agreed or the Terms & Conditions feature is not enabled.

If either of following is true, the user will be required to agree to the current Terms & Conditions the next time they interact with GreenArrow Studio:

The user’s terms_and_conditions_version is null.
The user’s terms_and_conditions_version is less than the current version number and the Require on Updates option is set.

Set this to a value larger than any version number you might use to prevent the user from ever being required to agree.

If Terms & Conditions was previously enabled, then later disabled, this value might not be null when sent from the server. The API user may continue to carry this number forward or clear it to null.

Must be either null or a non-negative integer.
May only be set if the Terms & Conditions feature is enabled.
System Administrators are not required to agree to the Terms & Conditions.

default_html_editor
string

Users may select their preferred editor when creating new campaign contents. Existing campaign contents are not affected by a change of this option.

The available options include:

bee - A responsive content editor with a sophisticated editing interface. This is GreenArrow’s default and recommended campaign HTML editor.
tinymce - A simple graphical content editor. Formerly GreenArrow’s only graphical editor, this option is still available for users whom prefer it.
raw html - A basic textbox for editing raw HTML. This is an option suitable for users who wish to edit their HTML with another application and paste it into GreenArrow.

permissions
hash

The permissions hash has an entry for each of the following keys with the values being the available permissions.

Here’s an example of a valid permissions hash.

        {
          "mailing_list": [ "update" ],
          "autoresponder": [ "update" ],
          "seed_list": [ "create", "update", "delete" ]
        }

mailing_list array of strings	Valid options: `create`, `update`, `delete`.
subscriber array of strings	Valid options: `create`, `update`, `delete`, `read`, `import`, `export`.
segmentation_criteria array of strings	Valid options: `create`, `update`, `delete`.
autoresponder array of strings	Valid options: `create`, `update`, `delete`, `update_state`, `read_stats`.
web_form array of strings	Valid options: `create`, `update`, `delete`.
custom_field array of strings	Valid options: `create`, `update`, `delete`.
campaign array of strings	Valid options: `create`, `update`, `delete`, `send`, `update_state`, `read_stats`.
campaign/template array of strings	Valid options: `create`, `update`, `delete`.
seed_list array of strings	Valid options: `create`, `update`, `delete`.

password_failure_lockout
hash
/
read-only

This key pertains to the studio_user_login_lockout_duration configuration directive. Refer to that directive for more information on password failure lockouts.

is_locked_out boolean / read-only	This user is currently locked out and will be denied access to GreenArrow Studio, even if they present a valid password.
expires_at datetime / read-only	The time at which the user will again be permitted to sign into GreenArrow Studio. This will be `null` if `is_locked_out` is `false`.

Get a List of Users

Get a list of the basic details of login users.

URL

GET /ga/api/v2/users
GET /ga/api/v2/organizations/:organization_id/users

When accessed by a system admin, the /ga/api/v2/users endpoint will return all users system wide. If a system admin account needs to retrieve the users on a single organization, use the /ga/api/v2/organizations/:organization_id/users endpoint.

When accessed by any other API user, the /ga/api/v2/users endpoint will return the users on their organization.

Request Parameters

full_name string	Filter all users with that exact description (case insensitive).
full_name_contains string	Filter all users that contain that description (case insensitive).
email string	Filter all users with that exact email (case insensitive).
email_contains string	Filter all users that contain that email (case insensitive).
order_by string	Specify an api key field to sort the results by. Can be `full_name`, `email`, or `id`. `full_name` and `email` will be ordered case-insensitively. Defaults to `id`

Response

The response will be a JSON array where each element contains the “User Attributes” specified above.

This endpoint returns paginated records with a default page size of 2000.

Example

GET /ga/api/v2/users

HTTP/1.1 200 OK

{
  "success": true,
  "data": [
    {
      "id": 54,
      "full_name": "John Smith",
      "email": "[email protected]",
      "active": true,
      "role": "system_admin",
      "show_quick_tips": true,
      "permissions": {
        "mailing_list": [
          "create",
          "update",
          "delete"
        ],
        "subscriber": [
          "create",
          "update",
          "delete",
          "read",
          "import",
          "export"
        ],
        "segmentation_criteria": [
          "create",
          "update",
          "delete"
        ],
        "autoresponder": [
          "create",
          "update",
          "delete",
          "update_state",
          "read_stats"
        ],
        "web_form": [
          "create",
          "update",
          "delete"
        ],
        "custom_field": [
          "create",
          "update",
          "delete"
        ],
        "campaign": [
          "create",
          "update",
          "delete",
          "send",
          "update_state",
          "read_stats"
        ],
        "campaign/template": [
          "create",
          "update",
          "delete"
        ],
        "seed_list": [
          "create",
          "update",
          "delete"
        ]
      },
      "default_preview_recipients": [

      ],
      "password_failure_lockout": {
        "is_locked_out": false,
        "expires_at": null
      }
    },
    {
      "id": 55,
      "full_name": "William Green",
      "email": "[email protected]",
      "active": true,
      "role": "system_admin",
      "show_quick_tips": true,
      "permissions": {
        "mailing_list": [
          "create",
          "update",
          "delete"
        ],
        "subscriber": [
          "create",
          "update",
          "delete",
          "read",
          "import",
          "export"
        ],
        "segmentation_criteria": [
          "create",
          "update",
          "delete"
        ],
        "autoresponder": [
          "create",
          "update",
          "delete",
          "update_state",
          "read_stats"
        ],
        "web_form": [
          "create",
          "update",
          "delete"
        ],
        "custom_field": [
          "create",
          "update",
          "delete"
        ],
        "campaign": [
          "create",
          "update",
          "delete",
          "send",
          "update_state",
          "read_stats"
        ],
        "campaign/template": [
          "create",
          "update",
          "delete"
        ],
        "seed_list": [
          "create",
          "update",
          "delete"
        ]
      },
      "default_preview_recipients": [

      ],
      "password_failure_lockout": {
        "is_locked_out": false,
        "expires_at": null
      }
    },
    {
      "id": 56,
      "full_name": "Joe Johnson",
      "email": "[email protected]",
      "active": true,
      "role": "system_admin",
      "show_quick_tips": true,
      "permissions": {
        "mailing_list": [
          "create",
          "update",
          "delete"
        ],
        "subscriber": [
          "create",
          "update",
          "delete",
          "read",
          "import",
          "export"
        ],
        "segmentation_criteria": [
          "create",
          "update",
          "delete"
        ],
        "autoresponder": [
          "create",
          "update",
          "delete",
          "update_state",
          "read_stats"
        ],
        "web_form": [
          "create",
          "update",
          "delete"
        ],
        "custom_field": [
          "create",
          "update",
          "delete"
        ],
        "campaign": [
          "create",
          "update",
          "delete",
          "send",
          "update_state",
          "read_stats"
        ],
        "campaign/template": [
          "create",
          "update",
          "delete"
        ],
        "seed_list": [
          "create",
          "update",
          "delete"
        ]
      },
      "default_preview_recipients": [

      ],
      "password_failure_lockout": {
        "is_locked_out": false,
        "expires_at": null
      }
    },
    {
      "id": 57,
      "full_name": "MyString",
      "email": "[email protected]",
      "active": true,
      "role": "system_admin",
      "show_quick_tips": true,
      "permissions": {
        "mailing_list": [
          "create",
          "update",
          "delete"
        ],
        "subscriber": [
          "create",
          "update",
          "delete",
          "read",
          "import",
          "export"
        ],
        "segmentation_criteria": [
          "create",
          "update",
          "delete"
        ],
        "autoresponder": [
          "create",
          "update",
          "delete",
          "update_state",
          "read_stats"
        ],
        "web_form": [
          "create",
          "update",
          "delete"
        ],
        "custom_field": [
          "create",
          "update",
          "delete"
        ],
        "campaign": [
          "create",
          "update",
          "delete",
          "send",
          "update_state",
          "read_stats"
        ],
        "campaign/template": [
          "create",
          "update",
          "delete"
        ],
        "seed_list": [
          "create",
          "update",
          "delete"
        ]
      },
      "default_preview_recipients": [

      ],
      "password_failure_lockout": {
        "is_locked_out": false,
        "expires_at": null
      }
    }
  ],
  "error_code": null,
  "error_message": null,
  "page": 0,
  "per_page": 2000,
  "num_records": 4,
  "num_pages": 1
}

Get a Single User

Get all the basic details of a single user.

URL

GET /ga/api/v2/users/:id

Request Parameters

id
integer

The id of the user to get

Response

The response will be a JSON hash as described in the User Attributes section of this document.

Example

Note that the JSON response will not be “pretty formatted” as it is below.

GET /ga/api/v2/users/58

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "id": 58,
    "full_name": "John Smith",
    "email": "[email protected]",
    "active": true,
    "role": "system_admin",
    "show_quick_tips": true,
    "permissions": {
      "mailing_list": [
        "create",
        "update",
        "delete"
      ],
      "subscriber": [
        "create",
        "update",
        "delete",
        "read",
        "import",
        "export"
      ],
      "segmentation_criteria": [
        "create",
        "update",
        "delete"
      ],
      "autoresponder": [
        "create",
        "update",
        "delete",
        "update_state",
        "read_stats"
      ],
      "web_form": [
        "create",
        "update",
        "delete"
      ],
      "custom_field": [
        "create",
        "update",
        "delete"
      ],
      "campaign": [
        "create",
        "update",
        "delete",
        "send",
        "update_state",
        "read_stats"
      ],
      "campaign/template": [
        "create",
        "update",
        "delete"
      ],
      "seed_list": [
        "create",
        "update",
        "delete"
      ]
    },
    "default_preview_recipients": [

    ],
    "password_failure_lockout": {
      "is_locked_out": false,
      "expires_at": null
    }
  },
  "error_code": null,
  "error_message": null
}

Create a New User

Create a new user on the current organization.

URL

POST /ga/api/v2/users

Request Parameters

The request body should be a JSON hash as described in the User Attributes section of this document.

Response

The response will be a JSON object in the same format as the response to the users index.

Example

Note that the JSON response will not be “pretty formatted” as it is below.

POST /ga/api/v2/users

{
  "user": {
    "password1": "password",
    "password2": "password",
    "full_name": "My new user",
    "email": "[email protected]",
    "active": true,
    "role": "standard"
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "id": 78,
    "full_name": "My new user",
    "email": "[email protected]",
    "active": true,
    "role": "standard",
    "show_quick_tips": true,
    "permissions": {
      "mailing_list": [
        "create",
        "update",
        "delete"
      ],
      "subscriber": [
        "create",
        "update",
        "delete",
        "read",
        "import",
        "export"
      ],
      "segmentation_criteria": [
        "create",
        "update",
        "delete"
      ],
      "autoresponder": [
        "create",
        "update",
        "delete",
        "update_state",
        "read_stats"
      ],
      "web_form": [
        "create",
        "update",
        "delete"
      ],
      "custom_field": [
        "create",
        "update",
        "delete"
      ],
      "campaign": [
        "create",
        "update",
        "delete",
        "send",
        "update_state",
        "read_stats"
      ],
      "campaign/template": [
        "create",
        "update",
        "delete"
      ],
      "seed_list": [
        "create",
        "update",
        "delete"
      ]
    },
    "default_preview_recipients": [

    ],
    "terms_and_conditions_version": null,
    "password_failure_lockout": {
      "is_locked_out": false,
      "expires_at": null
    }
  },
  "error_code": null,
  "error_message": null
}

Update an Existing User

URL

PUT /ga/api/v2/users/:id

Request Parameters

The request body should be a JSON hash as described in the User Attributes section of this document.

Response

The response will be a JSON object in the same format as the response to the users index.

Example

PUT /ga/api/v2/users/79

{
  "user": {
    "full_name": "My updated name"
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "id": 79,
    "full_name": "My updated name",
    "email": "[email protected]",
    "active": true,
    "role": "system_admin",
    "show_quick_tips": true,
    "permissions": {
      "mailing_list": [
        "create",
        "update",
        "delete"
      ],
      "subscriber": [
        "create",
        "update",
        "delete",
        "read",
        "import",
        "export"
      ],
      "segmentation_criteria": [
        "create",
        "update",
        "delete"
      ],
      "autoresponder": [
        "create",
        "update",
        "delete",
        "update_state",
        "read_stats"
      ],
      "web_form": [
        "create",
        "update",
        "delete"
      ],
      "custom_field": [
        "create",
        "update",
        "delete"
      ],
      "campaign": [
        "create",
        "update",
        "delete",
        "send",
        "update_state",
        "read_stats"
      ],
      "campaign/template": [
        "create",
        "update",
        "delete"
      ],
      "seed_list": [
        "create",
        "update",
        "delete"
      ]
    },
    "default_preview_recipients": [

    ],
    "password_failure_lockout": {
      "is_locked_out": false,
      "expires_at": null
    }
  },
  "error_code": null,
  "error_message": null
}

Clear a user’s password failure lockout

This endpoint pertains to the studio_user_login_lockout_duration configuration directive. Refer to that directive for more information on password failure lockouts.

URL

PUT /ga/api/v2/users/:id/reset_password_failure_lockout

Request Parameters

The body for this request should be a blank JSON object.

{}

Response

result
string

The result of clearing the user’s lockout. This can have the following values.

lockout_cleared	The user was locked out and that lockout has been cleared. The user can resume attempting to sign in.
not_locked_out	The user was not locked out. No action was taken. If the user has password failure attempts in progress, those attempts can result in a lockout.

Example

PUT /ga/api/v2/users/66/reset_password_failure_lockout

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "result": "lockout_cleared"
  },
  "error_code": null,
  "error_message": null
}

Delete a User

Delete a user with the given user ID.

URL

DELETE /ga/api/v2/users/:id

Request Parameters

id
integer

The id of the user to delete

Response

An empty successful response to this request indicates that the user was successfully deleted.

Example

Note that the JSON response will not be “pretty formatted” as it is below.

DELETE /ga/api/v2/users/58

HTTP/1.1 200 OK

{
  "success": true,
  "data": null,
  "error_code": null,
  "error_message": null
}