REST API Specification – Users

Posted by | Leave a Comment

Note: In all API calls, replace the % and example values between the % signs with your own variable values.

Get User

Replace %id% with the id of the user that you want to retrieve, %sessionId% and %token% with ‘sessionId’ and ‘token’ variables returned by the authentication process.

  • Description: Retrieve user by id.
  • URL structure: http://zurmo_url/index.php/users/user/api/read/%id%
  • Method: GET
  • HTTP header parameters:
    Accept: application/json
    ZURMO_API_REQUEST_TYPE: REST
    ZURMO_SESSION_ID: %sessionId%
    ZURMO_TOKEN: %token%
  • Parameters: None
  • PHP sample: 
    $authenticationData = login('super','super');
//Add code to check if user is logged successfully

$id = 1; // Change this with value of user id

$headers = array(
    'Accept: application/json',
    'ZURMO_SESSION_ID: ' . $authenticationData['sessionId'],
    'ZURMO_TOKEN: ' . $authenticationData['token'],
    'ZURMO_API_REQUEST_TYPE: REST',
);
$response = ApiRestHelper::createApiCall('http://zurmo_url/index.php/users/user/api/read/' . $id, 'GET', $headers);
// Decode json data
$response = json_decode($response, true);
if ($response['status'] == 'SUCCESS')
{
    $user = $response['data'];
    //Do something with user
}
else
{
    // Error, for example if we provided invalid user id
    $errors = $response['errors'];
    // Do something with errors
}
  • Return:
    Data contains user info.

    {
  "status":"SUCCESS",
  "data":{
    "id":2,
    "createdDateTime":"2012-05-07 13:27:49",
    "modifiedDateTime":"2012-05-07 13:27:49",
    "createdByUser":{
      "id":1,
      "username":"super"
    },
    "modifiedByUser":{
      "id":1,
      "username":"super"
    },
    "language":null,
    "timeZone":"UTC",
    "username":"petersmith",
    "currency":null,
    "manager":null,
    "department":null,
    "firstName":"PeterSmith",
    "jobTitle":null,
    "lastName":"PeterSmithson",
    "mobilePhone":null,
    "officePhone":null,
    "officeFax":null,
    "primaryAddress":null,
    "primaryEmail":null,
    "title":{
      "id":2,
      "value":"Mr."
    }
  },
  "message":null,
  "errors":null
}

Delete User

Replace %id% with the id of user that you want to delete, %sessionId% and %token% with ‘sessionId’ and ‘token’ variables returned by the authentication process.

  • Description: Delete user by id.
  • URL structure: http://zurmo_url/index.php/users/user/api/delete/%id%
  • Method: DELETE
  • HTTP header parameters:
    Accept: application/json
    ZURMO_API_REQUEST_TYPE: REST
    ZURMO_SESSION_ID: %sessionId%
    ZURMO_TOKEN: %token%
  • Parameters: None
  • PHP sample: 
    $id = 1; // Change this value to user id that you want to delete
$authenticationData = login('super','super');
//Add code to check if user is logged successfully

$headers = array(
    'Accept: application/json',
    'ZURMO_SESSION_ID: ' . $authenticationData['sessionId'],
    'ZURMO_TOKEN: ' . $authenticationData['token'],
    'ZURMO_API_REQUEST_TYPE: REST',
);
$response = ApiRestHelper::createApiCall('http://zurmo_url/index.php/users/user/api/delete/' . $id, 'DELETE', $headers);
$response = json_decode($response, true);
if ($response['status'] == 'SUCCESS')
{
    // Inform user that user is deleted
}
else
{
    // Error, for example if we provided invalid user id
    $errors = $response['errors'];
    // Do something with errors
}
  • Return: 
    {
  "status":"SUCCESS",
  "data":null,
  "message":null,
  "errors":null
}

Create New User

Replace %sessionId% and %token% with ‘sessionId’ and ‘token’ variables returned by the authentication process.

  • Description: Create new user
  • URL structure: http://zurmo_url/index.php/users/user/api/create/
  • Method: POST
  • HTTP header parameters:
    Accept: application/json
    ZURMO_API_REQUEST_TYPE: REST
    ZURMO_SESSION_ID: %sessionId%
    ZURMO_TOKEN: %token%
  • Parameters: 
    $data = Array
(
    [firstName] => Michael
    [lastName] => Smith
    [jobTitle] => President
    [department] => Sales
    [officePhone] => 653-235-7824
    [mobilePhone] => 653-235-7821
    [officeFax] => 653-235-7834
    [username] => diggy011
    [password] => diggy011
    [language] => en
    [timeZone] => America/Chicago
    [title] => Array
        (
            [value] => Dr.
        )

    [manager] => Array
        (
            [id] => 3
        )

    [primaryEmail] => Array
        (
            [emailAddress] => a@example.com
            [optOut] => 1
        )

    [primaryAddress] => Array
        (
            [street1] => 129 Noodle Boulevard
            [street2] => Apartment 6000A
            [city] => Noodleville
            [postalCode] => 23453
            [country] => The Good Old US of A
        )

    [currency] => Array
        (
            [id] => 1
        )

)
  • PHP sample: 
    $authenticationData = login('super','super');
//Add code to check if user is logged successfully

$headers = array(
    'Accept: application/json',
    'ZURMO_SESSION_ID: ' . $authenticationData['sessionId'],
    'ZURMO_TOKEN: ' . $authenticationData['token'],
    'ZURMO_API_REQUEST_TYPE: REST',
);
$data = Array
(
    'firstName' => 'Michael',
    'lastName' => 'Smith',
    'jobTitle' => 'President',
    'department' => 'Sales',
    'officePhone' => '653-235-7824',
    'mobilePhone' => '653-235-7821',
    'officeFax' => '653-235-7834',
    'username' => 'diggy011',
    'password' => 'diggy011',
    'language' => 'en',
    'timeZone' => 'America/Chicago',
    'title' => Array
        (
            'value' => 'Dr.'
        ),

    'manager' => Array
        (
            'id' => 3
        ),

    'primaryEmail' => Array
        (
            'emailAddress' => 'a@example.com',
            'optOut' => 1
        ),

    'primaryAddress' => Array
        (
            'street1' => '129 Noodle Boulevard',
            'street2' => 'Apartment 6000A',
            'city' => 'Noodleville',
            'postalCode' => '23453',
            'country' => 'The Good Old US of A'
        ),

    'currency' => Array
        (
            'id' => 1
        )

);

$response = ApiRestHelper::createApiCall('http://zurmo_url/index.php/users/user/api/create/', 'POST', $headers, array('data' => $data));
$response = json_decode($response, true);

if ($response['status'] == 'SUCCESS')
{
    $user = $response['data'];
    //Do something with user data
}
else
{
    // Error
    $errors = $response['errors'];
    // Do something with errors, show them to user
}
  • Return: 
    {
  "status":"SUCCESS",
  "data":{
    "id":4,
    "language":"en",
    "timeZone":"America\/Chicago",
    "username":"diggy011",
    "currency":{
      "id":1
    },
    "manager":{
      "id":3,
      "username":"smith45"
    },
    "createdDateTime":"2012-05-07 13:37:50",
    "modifiedDateTime":"2012-05-07 13:37:50",
    "createdByUser":{
      "id":1,
      "username":"super"
    },
    "modifiedByUser":{
      "id":1,
      "username":"super"
    },
    "department":"Sales",
    "firstName":"Michael",
    "jobTitle":"President",
    "lastName":"Smith",
    "mobilePhone":"653-235-7821",
    "officePhone":"653-235-7824",
    "officeFax":"653-235-7834",
    "primaryAddress":{
      "id":1,
      "city":"Noodleville",
      "country":"The Good Old US of A",
      "invalid":"0",
      "latitude":null,
      "longitude":null,
      "postalCode":"23453",
      "street1":"129 Noodle Boulevard",
      "street2":"Apartment 6000A",
      "state":null
    },
    "primaryEmail":{
      "id":1,
      "emailAddress":"a@example.com",
      "isInvalid":null,
      "optOut":"1"
    },
    "title":{
      "id":4,
      "value":"Dr."
    }
  },
  "message":null,
  "errors":null
}

Update existing user

Replace %id% with the id of the user that you want to update, %sessionId% and %token% with ‘sessionId’ and ‘token’ variables returned by the authentication process.

  • Description: Update existing user by id
  • URL structure: http://zurmo_url/index.php/users/user/api/update/%id%
  • Method: PUT
  • HTTP header parameters:
    Accept: application/json
    ZURMO_API_REQUEST_TYPE: REST
    ZURMO_SESSION_ID: %sessionId%
    ZURMO_TOKEN: %token%
  • Parameters:
    All parameters are optional, so you can only provide properties that you want to update.
    For example:

    $data = Array
(
    [firstName] => John
)
  • PHP sample: 
    $id = 1; // Change this value to user id that you want to change
$authenticationData = login('super','super');
//Add code to check if user is logged successfully

$headers = array(
    'Accept: application/json',
    'ZURMO_SESSION_ID: ' . $authenticationData['sessionId'],
    'ZURMO_TOKEN: ' . $authenticationData['token'],
    'ZURMO_API_REQUEST_TYPE: REST',
);
// Change user first name
$data['firstName']                = "John";
$response = ApiRestHelper::createApiCall('http://zurmo_url/index.php/users/user/api/update/' . $id, 'PUT', $headers, array('data' => $data));
$response = json_decode($response, true);
if ($response['status'] == 'SUCCESS')
{
    $user = $response['data'];
    //Do something with user data
}
else
{
    // Error, for example if we provided invalid user id
    $errors = $response['errors'];
    // Do something with errors
}
  • Return:
    Code will return complete updated user info.

    {
  "status":"SUCCESS",
  "data":{
    "id":4,
    "language":"en",
    "timeZone":"America\/Chicago",
    "username":"diggy011",
    "currency":{
      "id":1
    },
    "manager":{
      "id":3,
      "username":"smith45"
    },
    "createdDateTime":"2012-05-07 13:37:50",
    "modifiedDateTime":"2012-05-07 13:37:50",
    "createdByUser":{
      "id":1,
      "username":"super"
    },
    "modifiedByUser":{
      "id":1,
      "username":"super"
    },
    "department":"Sales",
    "firstName":"John",
    "jobTitle":"President",
    "lastName":"Smith",
    "mobilePhone":"653-235-7821",
    "officePhone":"653-235-7824",
    "officeFax":"653-235-7834",
    "primaryAddress":{
      "id":1,
      "city":"Noodleville",
      "country":"The Good Old US of A",
      "invalid":"0",
      "latitude":null,
      "longitude":null,
      "postalCode":"23453",
      "street1":"129 Noodle Boulevard",
      "street2":"Apartment 6000A",
      "state":null
    },
    "primaryEmail":{
      "id":1,
      "emailAddress":"a@example.com",
      "isInvalid":null,
      "optOut":"1"
    },
    "title":{
      "id":4,
      "value":"Dr."
    }
  },
  "message":null,
  "errors":null
}

Search users

Replace %sessionId% and %token% with ‘sessionId’ and ‘token’ variables returned by the authentication process.

  • Description: Search users
  • URL structure: http://zurmo_url/index.php/users/user/api/list/filter/%searchFilter%
  • Method: GET
  • HTTP header parameters:
    Accept: application/json
    ZURMO_API_REQUEST_TYPE: REST
    ZURMO_SESSION_ID: %sessionId%
    ZURMO_TOKEN: %token%
  • Query parameters: 
    $searchFilter = Array
(
    [pagination] => Array
        (
            [page] => 1
            [pageSize] => 3
        )
    [search] => Array
        (
            [manager] => Array
                (
                    [id] => 1
                )
        )
    [sort] => username.desc
)
  • PHP sample: 
    $authenticationData = login('super','super');
//Add code to check if user is logged successfully

$headers = array(
    'Accept: application/json',
    'ZURMO_SESSION_ID: ' . $authenticationData['sessionId'],
    'ZURMO_TOKEN: ' . $authenticationData['token'],
    'ZURMO_API_REQUEST_TYPE: REST',
);
$searchParams = array(
    'pagination' => array(
        'page'     => 1,
        'pageSize' => 3,
    ),
    'search' => array(
        'manager' => array('id' => '1'),
    ),
    'sort' => 'username.desc',
);
// Get first page of results
$searchParamsQuery = http_build_query($searchParams);
$response = ApiRestTestHelper::createApiCall('http://zurmo_url/index.php/users/user/api/list/filter/' . $searchParamsQuery, 'GET', $headers);
$response = json_decode($response, true);
if ($response['status'] == 'SUCCESS')
{
    // Do something with results
    if ($response['data']['totalCount'] > 0)
    {
        foreach ($response['data']['items'] as $item)
        {
        // Print users
        }
    }
    else
    {
     // There are no users
    }
}
else
{
    $errors = $response['errors'];
    // Do something with errors
}
// Now get second page (you might wanted to check if there are results on second page first)
$searchParams = array(
    'pagination' => array(
        'page'     => 2,
        'pageSize' => 3,
    ),
    'manager' => array('id' => '1'),
    'sort' => 'username.desc',
);
// Get second page of results
$searchParamsQuery = http_build_query($searchParams);
$response = ApiRestTestHelper::createApiCall('http://zurmo_url/index.php/users/user/api/list/filter/' . $searchParamsQuery, 'GET', $headers);
$response = json_decode($response, true);
if ($response['status'] == 'SUCCESS')
{
    // Do something with results
    if ($response['data']['totalCount'] > 0)
    {
        foreach ($response['data']['items'] as $item)
        {
        // Print users
        }
    }
    else
    {
     // There are no users
    }
}
else
{
    $errors = $response['errors'];
    // Do something with errors
}
  • Return: 
    {
  "status":"SUCCESS",
  "data":{
    "totalCount":"8",
    "currentPage":2,
    "items":[
      {
        "id":3,
        "language":null,
        "timeZone":"UTC",
        "username":"smith45",
        "currency":null,
        "manager":null,
        "createdDateTime":"2012-05-07 13:58:34",
        "modifiedDateTime":"2012-05-07 13:58:34",
        "createdByUser":{
          "id":1,
          "username":"super"
        },
        "modifiedByUser":{
          "id":1,
          "username":"super"
        },
        "department":null,
        "firstName":"Super",
        "jobTitle":null,
        "lastName":"User",
        "mobilePhone":null,
        "officePhone":null,
        "officeFax":null,
        "primaryAddress":null,
        "primaryEmail":null,
        "title":{
          "id":3,
          "value":"Mr."
        }
      },
      {
        "id":7,
        "createdDateTime":"2012-05-07 13:58:37",
        "modifiedDateTime":"2012-05-07 13:58:37",
        "createdByUser":{
          "id":1,
          "username":"super"
        },
        "modifiedByUser":{
          "id":1,
          "username":"super"
        },
        "language":null,
        "timeZone":"UTC",
        "username":"second",
        "currency":null,
        "manager":null,
        "department":null,
        "firstName":"Second",
        "jobTitle":null,
        "lastName":"Secondson",
        "mobilePhone":null,
        "officePhone":null,
        "officeFax":null,
        "primaryAddress":null,
        "primaryEmail":null,
        "title":{
          "id":7,
          "value":"Mr."
        }
      },
    ]
  },
  "message":null,
  "errors":null
}

Users Advanced Search

Replace %sessionId% and %token% with ‘sessionId’ and ‘token’ variables returned by the authentication process.

  • Description: Search users
  • URL structure: http://zurmo_url/index.php/users/user/api/list/filter/
  • Method: GET, POST
  • HTTP header parameters:
    Accept: application/json
    ZURMO_API_REQUEST_TYPE: REST
    ZURMO_SESSION_ID: %sessionId%
    ZURMO_TOKEN: %token%
  • Query parameters: 
    $data = Array
(
    [dynamicSearch] => Array
        (
            [dynamicClauses] => Array
                (
                    [0] => Array
                        (
                            [attributeIndexOrDerivedType] => name
                            [structurePosition] => 1
                            [username] => Fi
                        )

                    [1] => Array
                        (
                            [attributeIndexOrDerivedType] => name
                            [structurePosition] => 2
                            [username] => Se
                        )

                )

            [dynamicStructure] => 1 OR 2
        )

    [pagination] => Array
        (
            [page] => 1
            [pageSize] => 2
        )

    [sort] => username.asc
)
  • PHP sample: 
    $authenticationData = login('super','super');
//Add code to check if user is logged successfully

$headers = array(
    'Accept: application/json',
    'ZURMO_SESSION_ID: ' . $authenticationData['sessionId'],
    'ZURMO_TOKEN: ' . $authenticationData['token'],
    'ZURMO_API_REQUEST_TYPE: REST',
);
$data = array(
    'dynamicSearch' => array(
        'dynamicClauses' => array(
        array(
            'attributeIndexOrDerivedType' => 'name',
            'structurePosition' => 1,
            'username' => 'Fi',
        ),
        array(
            'attributeIndexOrDerivedType' => 'name',
            'structurePosition' => 2,
            'username' => 'Se',
        ),
        ),
        'dynamicStructure' => '1 OR 2',
    ),
    'pagination' => array(
        'page'     => 1,
        'pageSize' => 2,
    ),
    'sort' => 'username.asc',
);
// Get first page of results
$response = ApiRestTestHelper::createApiCall('http://zurmo_url/index.php/users/user/api/list/filter/', 'POST', $headers, array('data' => $data));
$response = json_decode($response, true);
if ($response['status'] == 'SUCCESS')
{
    // Do something with results
    if ($response['data']['totalCount'] > 0)
    {
        foreach ($response['data']['items'] as $item)
        {
        // Print users
        }
    }
    else
    {
     // There are no users
    }
}
else
{
    $errors = $response['errors'];
    // Do something with errors
}
  • Return: 
    {
  "status":"SUCCESS",
  "data":{
    "totalCount":"8",
    "currentPage":2,
    "items":[
      {
        "id":3,
        "language":null,
        "timeZone":"UTC",
        "username":"smith45",
        "currency":null,
        "manager":null,
        "createdDateTime":"2012-05-07 13:58:34",
        "modifiedDateTime":"2012-05-07 13:58:34",
        "createdByUser":{
          "id":1,
          "username":"super"
        },
        "modifiedByUser":{
          "id":1,
          "username":"super"
        },
        "department":null,
        "firstName":"Super",
        "jobTitle":null,
        "lastName":"User",
        "mobilePhone":null,
        "officePhone":null,
        "officeFax":null,
        "primaryAddress":null,
        "primaryEmail":null,
        "title":{
          "id":3,
          "value":"Mr."
        }
      },
      {
        "id":7,
        "createdDateTime":"2012-05-07 13:58:37",
        "modifiedDateTime":"2012-05-07 13:58:37",
        "createdByUser":{
          "id":1,
          "username":"super"
        },
        "modifiedByUser":{
          "id":1,
          "username":"super"
        },
        "language":null,
        "timeZone":"UTC",
        "username":"second",
        "currency":null,
        "manager":null,
        "department":null,
        "firstName":"Second",
        "jobTitle":null,
        "lastName":"Secondson",
        "mobilePhone":null,
        "officePhone":null,
        "officeFax":null,
        "primaryAddress":null,
        "primaryEmail":null,
        "title":{
          "id":7,
          "value":"Mr."
        }
      },
    ]
  },
  "message":null,
  "errors":null
}

Leave a Comment