REST API Specification – Accounts

Posted by | Leave a Comment

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

Get Account

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

  • Description: Retrieve account by id.
  • URL structure: http://zurmo_url/index.php/accounts/account/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 account 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/accounts/account/api/read/' . $id, 'GET', $headers);
// Decode json data
$response = json_decode($response, true);
if ($response['status'] == 'SUCCESS')
{
    $account = $response['data'];
    //Do something with account
}
else
{
    // Error, for example if we provided invalid account id
    $errors = $response['errors'];
    // Do something with errors
}
  • Return:
    Data contains account info.

    {
  "status":"SUCCESS",
  "data":{
    "id":1,
    "createdDateTime":"2012-03-20 10:51:45",
    "modifiedDateTime":"2012-03-20 10:51:45",
    "createdByUser":{
      "id":1,
      "username":"super"
    },
    "modifiedByUser":{
      "id":1,
      "username":"super"
    },
    "owner":{
      "id":1,
      "username":"super"
    },
    "annualRevenue":null,
    "description":null,
    "employees":null,
    "name":"First Account",
    "officePhone":null,
    "officeFax":null,
    "website":null,
    "billingAddress":null,
    "industry":{
      "id":2,
      "value":"Automotive"
    },
    "primaryEmail":null,
    "secondaryEmail":null,
    "shippingAddress":null,
    "type":{
      "id":3,
      "value":"Customer"
    }
  },
  "message":null,
  "errors":null
}

Delete Account

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

  • Description: Delete account by id.
  • URL structure: http://zurmo_url/index.php/accounts/account/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 account 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/accounts/account/api/delete/' . $id, 'DELETE', $headers);
$response = json_decode($response, true);
if ($response['status'] == 'SUCCESS')
{
    // Inform user that account is deleted
}
else
{
    // Error, for example if we provided invalid account id
    $errors = $response['errors'];
    // Do something with errors
}
  • Return: 
    {
  "status":"SUCCESS",
  "data":null,
  "message":null,
  "errors":null
}

Create New Account

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

  • Description: Create new account
  • URL structure: http://zurmo_url/index.php/accounts/account/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
(
    [name] => My Company
    [officePhone] => 6438238
    [officeFax] => 6565465436
    [employees] => 100
    [website] => http://www.google.com
    [annualRevenue] => 1000000
    [description] => Some Description
    [industry] => Array
        (
            [value] => Financial Services
        )

    [type] => Array
        (
            [value] => Customer
        )

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

    [secondaryEmail] => Array
        (
            [emailAddress] => b@example.com
            [optOut] => 0
            [isInvalid] => 1
        )

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

    [shippingAddress] => Array
        (
            [street1] => 25 de Agosto 2543
            [street2] => Local 3
            [city] => Ciudad de Los Fideos
            [postalCode] => 5123-4
            [country] => Latinoland
        )
)
  • 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
(
    'name' => 'My Company',
    'officePhone' => '6438238',
    'officeFax' => '6565465436',
    'employees' => '100',
    'website' => 'http://www.google.com',
    'annualRevenue' => '1000000',
    'description' => 'Some Description',
    'industry' => Array
        (
            'value' => 'Financial Services',
        ),
    'type' => Array
        (
            'value' => 'Customer',
        ),
    'primaryEmail' => Array
        (
            'emailAddress' => 'a@example.com',
            'optOut' => '1'
        ),
    'secondaryEmail' => Array
        (
            'emailAddress' => 'b@example.com'
            'optOut' => '0'
            'isInvalid' => '1'
        ),
    'billingAddress' => Array
        (
            'street1' => '129 Noodle Boulevard',
            'street2' => 'Apartment 6000A',
            'city' => 'Noodleville',
            'postalCode' => '23453',
            'country' => 'The Good Old US of A',
        ),
    'shippingAddress' => Array
        (
            'street1' => '25 de Agosto 2543',
            'street2' => 'Local 3',
            'city' => 'Ciudad de Los Fideos',
            'postalCode' => '5123-4',
            'country' => 'Latinoland',
        ),
    // Add relations(if any)
    'modelRelations' => array
        (
            'accounts' => array(
                array(
                    'action' => 'add',
                    'modelId' => 2
                ),
            ),
            'contacts' => array(
                array(
                    'action' => 'add',
                    'modelId' => 3
                ),
            ),
        ),
);

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

if ($response['status'] == 'SUCCESS')
{
    $account = $response['data'];
    //Do something with account data
}
else
{
    // Error
    $errors = $response['errors'];
    // Do something with errors, show them to user
}
  • Return: 
    {
  "status":"SUCCESS",
  "data":{
    "id":2,
    "annualRevenue":"1000000",
    "description":"Some Description",
    "employees":"100",
    "name":"My Company",
    "officePhone":"6438238",
    "officeFax":"6565465436",
    "website":"http://www.google.com",
    "billingAddress":{
      "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
    },
    "industry":{
      "id":4,
      "value":"Financial Services"
    },
    "primaryEmail":{
      "id":1,
      "emailAddress":"a@example.com",
      "isInvalid":null,
      "optOut":"1"
    },
    "secondaryEmail":{
      "id":2,
      "emailAddress":"b@example.com",
      "isInvalid":"1",
      "optOut":"0"
    },
    "shippingAddress":{
      "id":2,
      "city":"Ciudad de Los Fideos",
      "country":"Latinoland",
      "invalid":"0",
      "latitude":null,
      "longitude":null,
      "postalCode":"5123-4",
      "street1":"25 de Agosto 2543",
      "street2":"Local 3",
      "state":null
    },
    "type":{
      "id":5,
      "value":"Customer"
    },
    "owner":{
      "id":1,
      "username":"super"
    },
    "createdDateTime":"2012-03-20 11:07:54",
    "modifiedDateTime":"2012-03-20 11:07:54",
    "createdByUser":{
      "id":1,
      "username":"super"
    },
    "modifiedByUser":{
      "id":1,
      "username":"super"
    }
  },
  "message":null,
  "errors":null
}

Update existing account

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

  • Description: Update existing account by id
  • URL structure: http://zurmo_url/index.php/accounts/account/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
(
    [name] => My Company 2
    [employees] => 200
)
  • PHP sample 
    $id = 1; // Change this value to account 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 account name and number of employees
$data['name']                = "My Company 2";
$data['employees']                = "200";

// Add and remove some relations
$data['modelRelations'] => array
        (
            'accounts' => array(
                array(
                    'action' => 'add',
                    'modelId' => 2
                ),
                array(
                    'action' => 'remove',
                    'modelId' => 3
                ),
            ),
            'contacts' => array(
                array(
                    'action' => 'add',
                    'modelId' => 3
                ),
            ),
        );

$response = ApiRestHelper::createApiCall('http://zurmo_url/index.php/accounts/account/api/update/' . $id, 'PUT', $headers, array('data' => $data));
$response = json_decode($response, true);
if ($response['status'] == 'SUCCESS')
{
    $account = $response['data'];
    //Do something with account data
}
else
{
    // Error, for example if we provided invalid account id
    $errors = $response['errors'];
    // Do something with errors
}
  • Return:
    Code will return complete updated account info.

    {
  "status":"SUCCESS",
  "data":{
    "id":2,
    "annualRevenue":"1000000",
    "description":"Some Description",
    "employees":"200",
    "name":"My Company 2",
    "officePhone":"6438238",
    "officeFax":"6565465436",
    "website":"http://www.google.com",
    "billingAddress":{
      "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
    },
    "industry":{
      "id":4,
      "value":"Financial Services"
    },
    "primaryEmail":{
      "id":1,
      "emailAddress":"a@example.com",
      "isInvalid":null,
      "optOut":"1"
    },
    "secondaryEmail":{
      "id":2,
      "emailAddress":"b@example.com",
      "isInvalid":"1",
      "optOut":"0"
    },
    "shippingAddress":{
      "id":2,
      "city":"Ciudad de Los Fideos",
      "country":"Latinoland",
      "invalid":"0",
      "latitude":null,
      "longitude":null,
      "postalCode":"5123-4",
      "street1":"25 de Agosto 2543",
      "street2":"Local 3",
      "state":null
    },
    "type":{
      "id":5,
      "value":"Customer"
    },
    "owner":{
      "id":1,
      "username":"super"
    },
    "createdDateTime":"2012-03-20 11:07:54",
    "modifiedDateTime":"2012-03-20 11:17:54",
    "createdByUser":{
      "id":1,
      "username":"super"
    },
    "modifiedByUser":{
      "id":1,
      "username":"super"
    }
  },
  "message":null,
  "errors":null
}

Search accounts

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

  • Description: Search accounts
  • URL structure: http://zurmo_url/index.php/accounts/account/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
        (
            [industry] => Array
                (
                    [value] => Financial Services
                )

            [type] => Array
                (
                    [value] => Vendor
                )

            [owner] => Array
                (
                    [id] => 1
                )
        )
    [sort] => name.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(
        'industry' => array('value' => 'Financial Services'),
        'type' => array('value' => 'Vendor'),
        'owner' => array('id' => '1'),
    ),
    'sort' => 'name.desc',
);
// Get first page of results
$searchParamsQuery = http_build_query($searchParams);
$response = ApiRestTestHelper::createApiCall('http://zurmo_url/index.php/accounts/account/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 accounts
        }
    }
    else
    {
     // There are no accounts
    }
}
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,
    ),
    'search' => array(
        'firstName' => 'Alex',
    ),
    'sort' => 'firstName',
);
// Get second page of results
$searchParamsQuery = http_build_query($searchParams);
$response = ApiRestTestHelper::createApiCall('http://zurmo_url/index.php/accounts/account/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 accounts
        }
    }
    else
    {
     // There are no accounts
    }
}
else
{
    $errors = $response['errors'];
    // Do something with errors
}
  • Return: 
    {
  "status":"SUCCESS",
  "data":{
    "totalCount":"2",
    "currentPage":1,
    "items":[
    {
      "id":6,
      "createdDateTime":"2012-03-20 11:27:33",
      "modifiedDateTime":"2012-03-20 11:27:33",
      "createdByUser":{
        "id":1,
        "username":"super"
      },
      "modifiedByUser":{
        "id":1,
        "username":"super"
      },
      "owner":{
        "id":1,
        "username":"super"
      },
      "annualRevenue":null,
      "description":null,
      "employees":null,
      "name":"Forth Account",
      "officePhone":null,
      "officeFax":null,
      "website":null,
      "billingAddress":null,
      "industry":{
        "id":13,
        "value":"Financial Services"
      },
      "primaryEmail":null,
      "secondaryEmail":null,
      "shippingAddress":null,
      "type":{
        "id":14,
        "value":"Vendor"
      }
    },
    {
      "id":7,
      "createdDateTime":"2012-03-20 11:27:33",
      "modifiedDateTime":"2012-03-20 11:27:33",
      "createdByUser":{
        "id":1,
        "username":"super"
      },
      "modifiedByUser":{
        "id":1,
        "username":"super"
      },
      "owner":{
        "id":1,
        "username":"super"
      },
      "annualRevenue":null,
      "description":null,
      "employees":null,
      "name":"Fifth Account",
      "officePhone":null,
      "officeFax":null,
      "website":null,
      "billingAddress":null,
      "industry":{
        "id":15,
        "value":"Financial Services"
      },
      "primaryEmail":null,
      "secondaryEmail":null,
      "shippingAddress":null,
      "type":{
        "id":16,
        "value":"Vendor"
      }
    }
    ]
  },
  "message":null,
  "errors":null
}

Advanced Search For Accounts

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

  • Description: Search accounts
  • URL structure: http://zurmo_url/index.php/accounts/account/api/list/filter/
  • Method: POST, GET (accept both methods)
  • 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] => owner
                            [structurePosition] => 1
                            [owner] => Array
                                (
                                    [id] => 3
                                )

                        )

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

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

                )

            [dynamicStructure] => 1 AND (2 OR 3)
        )

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

    [sort] => name.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' => 'owner',
                'structurePosition' => 1,
                'owner' => array(
                    'id' => 1,
                ),
            ),
            array(
                'attributeIndexOrDerivedType' => 'name',
                'structurePosition' => 2,
                'name' => 'Fi',
            ),
            array(
                'attributeIndexOrDerivedType' => 'name',
                'structurePosition' => 3,
                'name' => 'Se',
            ),
        ),
        'dynamicStructure' => '1 AND (2 OR 3)',
    ),
    'pagination' => array(
        'page'     => 1,
        'pageSize' => 2,
    ),
    'sort' => 'name.asc',
);
// Get first page of results
$response = ApiRestTestHelper::createApiCall('http://zurmo_url/index.php/accounts/account/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 accounts
        }
    }
    else
    {
     // There are no accounts
    }
}
else
{
    $errors = $response['errors'];
    // Do something with errors
}
  • Return: 
    {
  "status":"SUCCESS",
  "data":{
    "totalCount":"2",
    "currentPage":1,
    "items":[
    {
      "id":6,
      "createdDateTime":"2012-03-20 11:27:33",
      "modifiedDateTime":"2012-03-20 11:27:33",
      "createdByUser":{
        "id":1,
        "username":"super"
      },
      "modifiedByUser":{
        "id":1,
        "username":"super"
      },
      "owner":{
        "id":1,
        "username":"super"
      },
      "annualRevenue":null,
      "description":null,
      "employees":null,
      "name":"Forth Account",
      "officePhone":null,
      "officeFax":null,
      "website":null,
      "billingAddress":null,
      "industry":{
        "id":13,
        "value":"Financial Services"
      },
      "primaryEmail":null,
      "secondaryEmail":null,
      "shippingAddress":null,
      "type":{
        "id":14,
        "value":"Vendor"
      }
    },
    {
      "id":7,
      "createdDateTime":"2012-03-20 11:27:33",
      "modifiedDateTime":"2012-03-20 11:27:33",
      "createdByUser":{
        "id":1,
        "username":"super"
      },
      "modifiedByUser":{
        "id":1,
        "username":"super"
      },
      "owner":{
        "id":1,
        "username":"super"
      },
      "annualRevenue":null,
      "description":null,
      "employees":null,
      "name":"Fifth Account",
      "officePhone":null,
      "officeFax":null,
      "website":null,
      "billingAddress":null,
      "industry":{
        "id":15,
        "value":"Financial Services"
      },
      "primaryEmail":null,
      "secondaryEmail":null,
      "shippingAddress":null,
      "type":{
        "id":16,
        "value":"Vendor"
      }
    }
    ]
  },
  "message":null,
  "errors":null
}

Leave a Comment