REST API Specification – CustomField

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

Get CustomField

Replace %customField% with the name of CustomField that you want to retrieve(for example with ‘Industries’), %sessionId% and %token% with ‘sessionId’ and ‘token’ variables returned by the authentication process.

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

    {
      "status":"SUCCESS",
      "data":{
        "Prospect":"Prospect",
        "Customer":"Customer",
        "Vendor":"Vendor"
      },
      "message":null,
      "errors":null
    }
    

List All CustomFields

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

  • Description: Show All Custom Fields
  • URL structure: http://zurmo_url/index.php/zurmo/customField/api/list/
  • 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
    
    $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/zurmo/customField/api/list/' . $id, 'GET', $headers);
    // Decode json data
    $response = json_decode($response, true);
    if ($response['status'] == 'SUCCESS')
    {
        $customFields = $response['data'];
        //Do something with data
    }
    else
    {
        // Error
        $errors = $response['errors'];
        // Do something with errors
    }
    
  • Return:
    Data contains CustomField info.

    {
      "status":"SUCCESS",
      "data":{
        "AccountTypes":{
          "Prospect":"Prospect",
          "Customer":"Customer",
          "Vendor":"Vendor"
        },
        "Industries":{
          "Automotive":"Automotive",
          "Adult Entertainment":"Adult Entertainment",
          "Financial Services":"Financial Services",
          "Mercenaries & Armaments":"Mercenaries & Armaments"
        }
      },
      "message":null,
      "errors":null
    }
    

Add New Values to Existing Custom Field

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

  • Description: Add New Values to Existing Custom Field
  • URL structure: http://zurmo_url/index.php/zurmo/customField/api/addValues/%customFieldDataName%
  • Method: PUT
  • HTTP header parameters:
    Accept: application/json
    ZURMO_API_REQUEST_TYPE: REST
    ZURMO_SESSION_ID: %sessionId%
    ZURMO_TOKEN: %token%
  • Parameters: Array of values that you want to add
  • 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(
        'values' => array('Provider', 'Client'),
    );
    $customFieldDataName = 'AccountTypes';
    $response = ApiRestHelper::createApiCall('http://zurmo_url/index.php/zurmo/customField/api/addValues/' . $customFieldDataName, 'GET', $headers);
    // Decode json data
    $response = json_decode($response, true);
    if ($response['status'] == 'SUCCESS')
    {
        $customFields = $response['data'];
        //Do something with data
    }
    else
    {
        // Error
        $errors = $response['errors'];
        // Do something with errors
    }
    
  • Return:
    Data contains all CustomField data.

    {
        "status":"SUCCESS",
        "data":
        {
            "Prospect":"Prospect",
            "Customer":"Customer",
            "Vendor":"Vendor",
            "Provider":"Provider",
            "Client":"Client"
        },
        "message":null,
        "errors":null
    }
    

Leave a Comment

  • Diply

    The PHP Sample contains some errors: the method should be PUT and the $data variable should be added to the end of the createApiCall function

  • Diply

    Also, the array with data should be formatted as follows:

    $data = array(
    ‘data’ => array(
    ‘values’ => array(‘Provider’, ‘Client’),
    ),
    );

    Without the ‘data’ index, the API will complain you should provide data.

  • Diply

    Another issue: when there’s an odd character in the resulting json (for example: ë), the json cannot be parsed properly (syntax error). Just took me 2 hours to figure that one out… This error only occurs when you add the character via the API; the json which is returned as a result of adding the values is then malformed.

    If you directly execute the ‘list’ command, the returned json is just fine and can be parsed without problems.

    Sample code:
    $data = array(
    ‘values’ => array(‘Ë’, ‘ë’),
    );
    $customFieldDataName = ‘AccountTypes’;
    $response = ApiRestHelper::createApiCall(‘http://zurmo_url/index.php/zurmo/customField/api/addValues/’ . $customFieldDataName, ‘GET’, $headers, array(‘data’ => $data));

    $response = json_decode($response, true);

    var_dump(json_last_error());