Users API

Users API

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.
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 all login users on the current organization.

URL

GET /ga/api/v2/users

Request Parameters

This API method does not require any additional parameters.

Response

The response will be a JSON array where each element contains the following keys.

Example Request

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

> GET /ga/api/v2/users HTTP/1.1
> Authorization: Basic MTo1ZTk2NDY1Yzg4M2YzMzA5ZjAxMDVhMmUxMDc2NjMyYjY4N2U2MWQy
> User-Agent: curl/7.24.0 (x86_64-apple-darwin12.0) libcurl/7.24.0 OpenSSL/0.9.8r zlib/1.2.5
> Host: sendsage-studio.dev
> Accept: */*
>
< HTTP/1.1 200 OK
< Cache-Control: no-cache, no-store, max-age=0, must-revalidate
< Pragma: no-cache
< Expires: Fri, 01 Jan 1990 00:00:00 GMT
< Content-Type: application/json; charset=utf-8
< X-UA-Compatible: IE=Edge
< Set-Cookie: _session_id=458055a23f26f844e74f8cd7300f6445; path=/; HttpOnly
< X-Request-Id: f6e40d578ed1d9c418cca45e1b7fe532
< X-Runtime: 0.025540
< Connection: close
{
   "success":true,
   "data":[
      {
         "active":true,
         "email":"admin@example.com",
         "full_name":"Organization Administrator",
         "id":1,
         "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"
            ]
         },
         "role":"system_admin",
         "default_preview_recipients":[],
         "show_quick_tips":true,
         "time_zone":null
      },
      {
         "active":true,
         "email":"api@example.com",
         "full_name":"API User",
         "id":2,
         "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"
            ]
         },
         "role":"system_admin",
         "default_preview_recipients":[],
         "show_quick_tips":true,
         "time_zone":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 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 Request

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

> POST /ga/api/v2/users HTTP/1.1
> Authorization: Basic MTo1ZTk2NDY1Yzg4M2YzMzA5ZjAxMDVhMmUxMDc2NjMyYjY4N2U2MWQy
> User-Agent: curl/7.24.0 (x86_64-apple-darwin12.0) libcurl/7.24.0 OpenSSL/0.9.8r zlib/1.2.5
> Host: sendsage-studio.dev
> Accept: */*
{
    "user": {
        "active":true,
        "email":"bob@example.com",
        "full_name":"The Second Administrator",
        "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":[],
        "role":"organization_admin"
    }
}
< HTTP/1.1 200 OK
< Cache-Control: no-cache, no-store, max-age=0, must-revalidate
< Pragma: no-cache
< Expires: Fri, 01 Jan 1990 00:00:00 GMT
< Content-Type: application/json; charset=utf-8
< X-UA-Compatible: IE=Edge
< Set-Cookie: _session_id=458055a23f26f844e74f8cd7300f6445; path=/; HttpOnly
< X-Request-Id: f6e40d578ed1d9c418cca45e1b7fe532
< X-Runtime: 0.025540
< Connection: close
{
   "success":true,
   "data":{
      "active":true,
      "email":"bob@example.com",
      "full_name":"The Second Administrator",
      "id":3,
      "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":[],
      "role":"system_admin",
      "show_quick_tips":true,
      "time_zone":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 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 Request

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

> PUT /ga/api/v2/users/3 HTTP/1.1
> Authorization: Basic MTo1ZTk2NDY1Yzg4M2YzMzA5ZjAxMDVhMmUxMDc2NjMyYjY4N2U2MWQy
> User-Agent: curl/7.24.0 (x86_64-apple-darwin12.0) libcurl/7.24.0 OpenSSL/0.9.8r zlib/1.2.5
> Host: sendsage-studio.dev
> Accept: */*
{
    "user": {
        "full_name":"The Second Administrator ZOMG"
    }
}
< HTTP/1.1 200 OK
< Cache-Control: no-cache, no-store, max-age=0, must-revalidate
< Pragma: no-cache
< Expires: Fri, 01 Jan 1990 00:00:00 GMT
< Content-Type: application/json; charset=utf-8
< X-UA-Compatible: IE=Edge
< Set-Cookie: _session_id=458055a23f26f844e74f8cd7300f6445; path=/; HttpOnly
< X-Request-Id: f6e40d578ed1d9c418cca45e1b7fe532
< X-Runtime: 0.025540
< Connection: close
{
   "success":true,
   "data":{
      "active":true,
      "email":"bob@example.com",
      "full_name":"The Second Administrator ZOMG",
      "id":3,
      "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":[],
      "role":"system_admin",
      "show_quick_tips":true,
      "time_zone":null
   }
}