API Documentation | User

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


_cid string
The primary key
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.
A string containing an RFC822 compatible email address (e.g. "support@circonus.com")
firstname string
The user's first name.
A string containing freeform text
lastname string
The user's last name.
A string containing freeform text


Fetching Users

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

GET /account/1234

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

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

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

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

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

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