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]/users//api/[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 |
|
json (default), |
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 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/demov0.4/usersuser/?format=xml&limit=5 |
Sample output:
Code Block | ||||
---|---|---|---|---|
| <users>
<user user_id="3c5a623af057e23a32ae4000cf291339" >
| |||
{
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",
"b4ccdba29e01a61ea099394737c4fbf7"
],
locations: ["26fc44e2792b4f2fa8ef86178f0a958e", "c1b029932ed442a6a846a4ea10e46a78"],
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 | ||
---|---|---|
| ||
<response> <objects type="list"> <object 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>numbers type="list"> <phone_number> <value>+50253311399</phone_number>value> <phone_number><value>+50253314588</phone_number>value> </phone_numbers> <groups> <group<groups idtype="9a0accdba29e01a61ea099394737c4fblist"> <value>9a0accdba29e01a61ea099394737c4fb</>value> <group id="b4ccdba29e01a61ea099394737c4fbf7" /> <value>b4ccdba29e01a61ea099394737c4fbf7</value> </groups> <user_data>data type="hash"> <data key="chw_id">13 <chw_id>13/43/DFA</data>chw_id> </user_data> </user>object> <user <object user_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>numbers type="list"> <phone_number> <value>+50253311388</phone_number>value> </phone_numbers> <groups type="list"/> <user_data>data type="hash"> <village>Patna</village> <husband_name>Bob Smith</husband_name> </user_data> </object> </objects> <meta <data key="village">Patna</data>type="hash"> <next type="null"/> <total_count type="integer">29</total_count> <previous type="null"/> <data key="husband_name">Bob Smith</data> </user_data> </user> ... </users> <limit type="integer">2</limit> <offset type="integer">0</offset> </meta> </response> |