Users API

Table of Contents
User Attributes
Get a List of Users
Get a Single User
Create a New User
Update an Existing 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
SendSage 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.

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`.

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": [

      ]
    },
    {
      "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": [

      ]
    },
    {
      "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": [

      ]
    },
    {
      "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": [

      ]
    }
  ],
  "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": [

    ]
  },
  "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": 66,
    "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
  },
  "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/67

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

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "id": 67,
    "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": [

    ]
  },
  "error_code": null,
  "error_message": null
}