API documentation

Retrieving and Editing Entities

Retrieving an Entity

To retrieve an entity from the API, use one of the get* methods listed in the API method index. These methods take an entity ID and (optionally) a rev identifier. (See the Revs and ETags documentation for additional information about revs and caching.)

Expected Response

The response for any get* method is typically a dictionary representation of the requested entity. For a detailed description of exactly which fields may be returned for each entity, see the corresponding documentation from the API response index.

For example, the array returned by getLead is documented in Lead.

If an entity is not returned, the response will be an error message or a notice that your currently cached entity is still valid.

Editing an Entity

To edit an entity, use one of the edit* methods listed in the API method index. These methods take an entity ID, a rev identifier, and an array containing new/updated values for the entity.

The rev identifier is mandatory for the edit* methods. See "Revs", below, for an overview of how revs are used in editing an entity.

Expected Responses

The response for any edit* method is typically a dictionary representation of the updated entity. (See "Expected Responses" for retrieving an entity, above.)

If an entity is not returned, the response will be an error message or a notice that you cannot edit the entity because your currently cached entity is invalid. (See "Revs", below, for an overview of how revs are used in editing an entity.)

Multi-Value Fields

Many entities have fields which can contain more than one value. For example, a Contact may have multiple addresses and phone numbers; and a Lead may have multiple Contacts.

Each of these fields, if present in a response, will include one value called --primary. This will be a duplicate of another value in the multi-value field; it represents the primary value (for example, a Contact's primary phone number).

Editing Multi-Value Fields

When you wish to add a value (for example, an additional phone number) to one of these multi-value fields, you must also include all preexisting values in that field. The edit* methods replace all existing values with whatever value(s) you supply in your API call.

This behavior allows you to delete values from multi-value fields using the edit* family of methods.

If a multi-value field is not included in the "changes" array you pass to the edit method, the preexisting values are not affected.

This behavior does not apply to fields that can only contain a single value (such as a Contact's name).

Custom Fields

Certain entity types (currently Leads, Accounts, and Contacts) support custom fields, which can be viewed and edited just like regular fields. In order to prevent name collisions with built-in fields, custom fields are contained within a dictionary with the key customFields.

Custom fields are rendered just like regular fields of the same type. Here's an example response for a getLead request on a lead with a currency custom field named "Budget" and a text custom field named "Reference ID":

"result": {
    "id": 1653,
    "entityType": "Leads",
    ...
    "customFields": {
        "Reference ID": "999-99-9999", 
        "Budget": {
            "currency": "USD",
            "amount": "200"
        }
    },
    ...
}

Editing Custom Fields

Editing custom fields can be done by including a customFields dictionary in the changes array you pass to the edit* method. To update or add a custom field, add an entry to customFields with the key set to the custom field's name and the value to the desired value. To delete a custom field value, do the same, but set the value to null.

Here's an example JSON-RPC request that will remove the value for the "Reference ID" field and change the value for the "Budget" field to €40.50 for the above lead:

{
    "jsonrpc": "2.0",
    "method": "editLead",
    "params": {
       "leadId": "1653",
       "rev": "9", 
       "lead": {
          "customFields": {
             "Budget": {
                "currency": "EUR",
                "amount": "40.50"
             },
             "Reference ID": null
          }
       }
    },
    "id": "a"
}

Revs

Revs are Nutshell's approach to application-level cache control. The Nutshell API issues a revision identifier (rev key) as part of its response each time you retrieve an entity.

When you call an edit* method, you must include the rev you have cached for the entity you intend to edit. If the entity has been changed on the server since you last retrieved it, the API will not let you make your changes. This prevents the possibility of accidental data loss.

For additional information on revs, see the Revs and ETags documentation.