You can also update information contact information; however, you are not allow to create or delete a user using the API.

Please refer User Field Table for the meaning of individual field.

LIST (GET /users.xml)

Retrieve list of active users, both active and deleted are included. To exclude deleted users, use active_only parameter.

Example 1: Listing of users

Retrieve list of users (only page 1 (first 100) of the users will be returned). You can use page parameter to return more pages. Page and per_page parameter can be used.

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \ 
-H "Accept: application/xml" \ 
-H "Content-Type: application/xml" \ "https://test_account.imonggo.com/api/users.xml" 

Sample Result: 

<?xml version="1.0" encoding="UTF-8"?> 
<users type="array"> 
  <user> 
    ... 
  </user> 
  <user> 
    .... 
  </user> 
   ... 
  </users> 

Sample result (if contents is empty): 

<users/>

Example 2: Listing of Active users Only

Retrieve list of users (only 1st 100 users will be returned). This parameter is useful when you are retrieving a complete set of active users only. If you are retrieving the updated user list, it is important to include the delete users so that you can also delete the local version of users.

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \ 
-H "Accept: application/xml" \ 
-H "Content-Type: application/xml" \ "https://test_account.imonggo.com/api/users.xml?active_only=1"

Return Codes:

CODE/STATUS	CONDITION
200 OK	if successful

GET (GET /user/{id}.xml)

Retrieve information on single user. Replace {id} with the user id. Please refer this page for return field information and meaning.

Example 1:

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \ 
-H "Accept: application/xml" \ 
-H "Content-Type: application/xml" \ "https://test_account.imonggo.com/api/users/21.xml" 

Sample result: 

<?xml version="1.0" encoding="UTF-8"?> 
<user> 
 <email>sarah@test.com</email> 
 <home_branch_id>8</home_branch_id>
 <id>21</id>
 <name>Sarah Smith</name>
 <status nil="true"></status>
 <role_code>manager</role_code>
 <utc_created_at>2011-04-23T01:20:32Z</utc_created_at>
 <utc_updated_at>2011-04-27T11:43:18Z</utc_updated_at> 
</user>

Return Codes:

CODE/STATUS	CONDITION
200 OK	if successful
404 Not found	if no user matches the id

Parameters for LIST (GET /users.xml) ##

Page Filters

Page filters are used in LIST to limit the users to be retrieved. You can combined page filter with Date Filters (before, after, from and to).

page: default of 1 (eg. page=1)
per_page: any number between 1 to 100 (e.g. per_page=10)

Date Filters

Date filtered are used in LIST to limit the users to be retrieved. Given date format is in "YYYY-MM-DD HH:MM:SS" specified in UTC time. Invalid date format will cause internal server error (status code: 500).

before: updated date < given date
after: updated date > given date
from: updated date >= give date
to: updated date <= give date

Status Filter

active_only: when setup to 1 to true, the list will exclude deleted users

Inquiry

q=count - returns a number of users
q=last_updated_at - returns the last updated date for your user database

Multiple Branches

If you have multiple branch and would like to confine the listing of users to selected branch, you can use the branch_id parameter. To get the list branches, you can use GET /branches.xml.

If branch id is not provided, the server return list of users of the entire account.

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \ -H "Accept: application/xml" \ -H "Content-Type: application/xml" \ "https://test_account.imonggo.com/api/users.xml?branch_id=10"

Additional Notes for Developers

When a user is deleted, the status will be "D"
Listing returns both active and deleted users.
In case the XML is not corrected formatted, the server will return 500 (Internal server error)

Proposed Algorithm for synchronizing user incrementally

Keep a local persistent variable: previous_last_updated_date (which is initially nil)
GET last_updated_date from server
GET users after previous_last_updated_date to last_updated_date
Start with page 1 until users return contains an empty array
Override local variable pervious_last_updated_date with last_updated_date

Note: When users downloaded contains status D, you should delete the local copy of the user if present.