API Documentation | User

Get basic information about the users on your account or a single user.

Fields

_cid string
The primary key
"/user/1234"
A string containing a user cid
contact_info object
Additional contact info for the user that may be used to contact the user when alerts are triggered.
An object
sms string
A 'telephone' number the user can receive text messages on (i.e. a MSISDN)
A string containing freeform text
xmpp string
A XMPP address the user can receive messages on (i.e. a jabber/google talk address)
A string containing freeform text
email string
The user's email address. The email address must conform to RFC822 and contain a fully qualified domain name.
"gordon.robinson@example.com"
A string containing an RFC822 compatible email address (e.g. "support@circonus.com")
firstname string
The user's first name.
"Gordon"
A string containing freeform text
lastname string
The user's last name.
"Robinson"
A string containing freeform text

Example

Fetching Users

Fetching details for a user is as simple as performing a GET on the user cid:

GET /account/1234
{"_cid":"/user/1234","firstname":"Gordon","email":"gordon.robinson@example.com","lastname":"Robinson"}

However, you can only access information on users that belong to the account associated with the API token you are using.

As well as using a known numerical user cid, you can also get the current user - the user your API token is associated with - by requesting the special /user/current cid:

GET /user/current
{"email":"gordon.robinson@example.com","firstname":"Gordon","_cid":"/user/1234","lastname":"Robinson"}

Updating Users

Changing the user's details can be achieved by sending JSON in a PUT method to the cid of that user:

PUT /user/current
{"email":"trash-gordon@example.com"}

As is normal with Circonus the PUT method returns the full JSON of the updated user in the response.

Listing Users

Users can be listed by performing a GET request on /user

GET /user
[{"email":"trash-gordon@example.com","firstname":"Gordon","_cid":"/user/1234","lastname":"Robinson"},{"lastname":"Robinson","_cid":"/user/1235","firstname":"Susan","email":"susan.robinson@example.com"},{"firstname":"Miles","email":"miles.robinson@example.com","_cid":"/user/1236","lastname":"Robinson"}]

You can also get a list of the users and what role they have in an account by using the Circonus account API and looking at the users field:

GET /account/current
{"state_prov":"NY","_cid":"/account/40231","_owner":"/user/12345","city":"New York City","country_code":"US","name":"robinsons","address1":"123 Sesame Street","address2":"","invites":[],"_usage":[{"_used":49,"_limit":50,"_type":"Host"}],"description":"The Account of Gordon and Susan","_contact_groups":[],"timezone":"America/New_York","users":[{"user":"/user/1234","role":"Admin"},{"user":"/user/1235","role":"Admin"},{"role":"Normal","user":"/user/1236"}]}

Creating and Deleting Users

Currently users can only be created via people signing up through the website; People may be invited to the account by modifying the invites field of the account with the Circonus account API:

PUT /account/current
{"invites":[{"email":"dorthy@example.com","role":"Normal"},{"email":"lee@example.com","role":"Normal"}]}

Users cannot be deleted directly, though they can be removed from an account with the API by modifying the roles field of the account with the Circonus account API:

PUT /account/current
{"users":[{"user":"/user/1234","role":"Admin"},{"role":"Admin","user":"/user/1235"}]}