Page Comparison

Purpose: get a list of users, or a single user. The list of users may be presented to the end user as a simple list of user names, where each name includes a hyperlink to access a list of cases owned by the user.

Base URL: https://www.commcarehq.org/a/[domain]/api/[version]/user/

Single User URL: https://www.commcarehq.org/a/[domain]/api/v1/users//[version]/user/[user_id]

Permissions Required: Edit Mobile Workers & Edit Access API's

Authentication and Usage: All URL endpoints should be utilized as part of a cURL authentication command. For more information, please review https://dimagi.atlassian.net/wiki/x/LwXKfw.

Input parameters:

Name	Description	Example
format	data format

(optional)

Supported:

xml

json (default),

json

xml	format=xml
group	Group UUID (optional)	group=ac9d34ff59cf6388e4f5804b12276d8a
archived	List archived users instead of active ones	archived=true
extras	Adds extra data fields (this can slow down the API) for recent user activity	extras=true

Output values:

Name	Description	Example	Notes
id	User UUID	3c5a623af057e23a32ae4000cf291339
username	User name of user, including domain	jdoe@example.commcarehq.org
first_name	First name of user	John
last_name	Last name of user	Doe
default_phone_number	Primary phone number of user	+50253311399
email	Email address of user	john.doe@example.org
phone_numbers	List of all phone numbers of the user	(see examples)
groups	List of all group ids belonging to the user	(see examples)
primary_location	The location id of the primary location of the user	"26fc44e2792b4f2fa8ef86178f0a958e"
locations	A list of location ids that the user is assigned to	["26fc44e2792b4f2fa8ef86178f0a958e", "c1b029932ed442a6a846a4ea10e46a78"]
user_data	Any additional custom data associated with the user	(see examples)	If the property begins with a number, it will not be returned when using XML

Sample usage:

Code Block
https://www.commcarehq.org/a/demo/api/v1v0.4/usersuser/?format=xml&limit=5

Sample output:

JSON:

{users: [

Code Block

language	javascript

js

{
    meta: {
        limit: 2,
        next: null,
        offset: 0,
        previous: null,
        total_count: 29
    },
    objects: [{
    {    type: "user",
        id: "3c5a623af057e23a32ae4000cf291339",
        username: "jdoe@example.commcarehq.org",
        first_name: "John",
        last_name: "Doe",
        default_phone_number: "+50253311399",
        email: "jdoe@example.org",
        phone_numbers: [
 
        "+50253311399",
          "+50253314588"
        ],
        groups: [
        "9a0accdba29e01a61ea099394737c4fb",
        "9a0accdba29e01a61ea099394737c4fb"b4ccdba29e01a61ea099394737c4fbf7"
        ],
        locations: ["26fc44e2792b4f2fa8ef86178f0a958e", "b4ccdba29e01a61ea099394737c4fbf7c1b029932ed442a6a846a4ea10e46a78"], 
        primary_location: "26fc44e2792b4f2fa8ef86178f0a958e"
 ],       user_data: {
            "chw_id": "13/43/DFA"
        }
    }, {
    {    type: "user",
        id: "3c5a623af057e23a32ae4000cf2943248",
        username: "jsmith@example.commcarehq.org",
        first_name: "Jane",
        last_name: "Smith",
        default_phone_number: "+50253311388",
        email: "jsmith@example.org",
        phone_numbers: [
 
        "+50253311388"
        ],
        locations: [],
        primary_location: null
        groups: [],
        user_data: {
            "village": "Patna",
	
            "husband_name": "Bob Smith"
      }
    },
    ...}]
]}

XML:

Code Block

language	html/xml

<users><response>
	<objects type="list">
		<object  <user id="3c5a623af057e23a32ae4000cf291339" >
        			<username>jdoe@example.commcarehq.org</username>
        			<first_name>John</first_name>
        			<last_name>Doe</last_name>
        			<default_phone_number>+50253311399</default_phone_number>
        			<email>jdoe@example.org</email>
        			<phone_numbers>
            <phone_number>+50253311399</phone_number>
            <phone_number>+50253314588</phone_number>
        numbers type="list">
				<value>+50253311399</value>
				<value>+50253314588</value>
			</phone_numbers>
        <groups>
            <group id="9a0accdba29e01a61ea099394737c4fb" />
            <group id="b4ccdba29e01a61ea099394737c4fbf7" /> 
        </groups>
        <user_data>
                			<groups type="list">
				<value>9a0accdba29e01a61ea099394737c4fb</value>
				<value>b4ccdba29e01a61ea099394737c4fbf7</value>
			</groups>
			<user_data type="hash">
				<chw_id>13/43/DFA</chw_id>
        			</user_data>
    		</user>
    <userobject>
		<object id="3c5a623af057e23a32ae4000cf2943248">
        			<username>jsmith@example.commcarehq.org</username>
        			<first_name>Jane</first_name>
        			<last_name>Smith</last_name>
        			<default_phone_number>+50253311388</default_phone_number>
        			<email>jsmith@example.org</email>
        			<phone_numbers>
            <phone_number>+50253311388</phone_number>
        numbers type="list">
				<value>+50253311388</value>
			</phone_numbers>
        <groups />
        <user_data>
                <village>Patna</village>
                			<groups type="list"/>
			<user_data type="hash">
				<village>Patna</village>
				<husband_name>Bob Smith</husband_name>
			</user_data>
		</object>
	</objects>
	<meta type="hash">
		<next type="null"/>
 </user_data>
    </user>
    ...
</users>		<total_count type="integer">29</total_count>
		<previous type="null"/>
		<limit type="integer">2</limit>
		<offset type="integer">0</offset>
	</meta>
</response>

Versions Compared

Old Version 16

New Version Current

Key