Keap API calls for custom fields

Keap (formerly Infusionsoft) offers a powerful Rest API. I’m working with it to keep one of our client’s Keap contacts in sync with the data stored in the web application database. Most of the API calls are straightforward. The documentation is clear and once you follow it, there is not much you should worry about.

Custom fields headache

The issue occurred when I tried to read custom fields configured by the client. The typical call for the single contact or contacts list was not returning custom fields configured. In fact, the typical response with the contact data returns something like this:

Looks like only the basic information is returned. Of course, there is an ability to add “optional properties” to the call. In the documentation, I found that “optional properties” is: Comma-delimited list of Contact properties to include in the response. (Some fields such as lead_source_id, custom_fields, and job_title aren’t included, by default.)

OK, so we can try to pull my custom field, right? But how to do this? What field name should I use? For instance, we have “Role” or “Group” custom fields. The problem was, that once I tried to pass these, I received an error: “The following optional-properties are unrecognized” followed by the list of fields.

So, how to check what optional properties can I use? Let’s try to call “Retrieve Contact Model” and see what the model contains. At the beginning of the response we have (some fields hid for security purposes):

Looks like there are in fact custom fields and there are Group and Role fields present. In the later part of the same API call response, I found the list of all possible optional properties:

There are no particular custom fields listed, but there is a “custom_fields” optional property. Let’s pass it to the “Get one contact” and see what happens:

As you can see, the custom fields are now included. Please note that there are no names provided. The custom fields variable is an array filled with objects. Each object contains an id and content. In my case (see contact model screenshots) I want to take a look at Group and Role which is ID of 16 and 18. In the above example, they are not defined.

How to update custom fields?

Once we are able to retrieve custom fields, you may ask how to adjust them. Assuming that we only want to change some fields, the typical contents of the API call to update the contact are:

{
  "family_name" : "NewFamilyName",
  "given_name" : "NewGivenName",
  "id" : 12345
}

In order to adjust custom fields, we need to create the same structure as in returned JSON – Array with objects, each of them containing an id and content:

{
  "family_name" : "NewFamilyName",
  "given_name" : "NewGivenName",
  "custom_fields" : [ 
    { "id" : 16, "content" : "New Group Name" },
    { "id" : 18, "content" : "New Role Name" }
  ],
  "id" : 12345
}

Once such payload is received by API, the fields provided in the call are updated and the other fields are left unchanged. This means that we can change only a particular custom field value while leaving others unchanged. The order within the array is not important – the ID of the fields dictates the place the value will be stored.