Custom Fields

View and manage custom fields and data-tag custom fields. For details on the difference between custom fields and data-tag custom fields the following article in our support portal details configuration and usage.

• tag - the data-tag the custom field relates to for data-tag custom fields
• label - custom field label
• text - used for list or text type custom fields
• date - used for date type custom fields
• boolean - used for checkbox custom fields, can be either true or false

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<customField>
  <id>1</id>
  <tag>Staff</tag>
  <label>NI Number</label>
  <text>12345678</text>
  <date>2011-03-13T00:00:00Z</date>
  <boolean>true</boolean>
</customField>{
  "customField": {
    "id": "1",
    "tag": "Staff",
    "label": "NI Number",
    "text": "12345678",
    "date": "2011-03-13T00:00:00Z",
    "boolean": "true"
  }
}
Show as JSONShow as XML

List Custom Fields for a Party, Opportunity and Case

List custom fields and data-tag custom fields for a specific party, opportunity or case. Only custom fields that have a value associated with them will be returned in the list or check box custom fields that have been “ticked”.

GET /api/party/:id/customfields
GET /api/opportuntity/:id/customfields
GET /api/kase/:id/customfields

Response

HTTP/1.1 200 OK

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<customFields>
  <customField>
    <id>1</id>
    <tag>Staff</tag>
    <label>NI Number</label>
    <text>12345678</text>
  </customField>
  <customField>
    <id>1</id>
    <tag>Staff</tag>
    <label>Start Date</label>
    <date>2011-03-13T00:00:00Z</date>
  </customField>
  <customField>
    <id>1</id>
    <label>Send newsletter</label>
    <boolean>true</boolean>
  </customField>
</customFields>{
  "customFields": {
    "customField": [
      {
        "id": "1",
        "tag": "Staff",
        "label": "NI Number",
        "text": "12345678"
      },
      {
        "id": "1",
        "tag": "Staff",
        "label": "Start Date",
        "date": "2011-03-13T00:00:00Z"
      },
      {
        "id": "1",
        "label": "Send newsletter",
        "boolean": "true"
      }
    ]
  }
}
Show as JSONShow as XML

List Custom Field Definitions

Retrieve the collection of custom field definitions configured in the account for Parties, Opportunities and Cases.

GET /api/party/customfield/definitions
GET /api/opportunity/customfield/definitions
GET /api/kase/customfield/definitions

Response

• tag name of the tag associated with the custom field for data-tag custom fields
• label The custom field label
• type Text, List, Date, Boolean
• option depending on the type will contain an optional regular expression for Text custom fields or a semi-colon separated list of options for List custom fields.
• forClass indicates if the custom field is intended for a PERSON or ORGANISATION record

HTTP/1.1 200 OK

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<customFieldDefinitions>
  <customFieldDefinition>
    <id>1</id>
    <tag>Staff</tag>
    <label>NI Number</label>
    <type>Text</type>
    <options>^[A-CEGHJ-PR-TW-Z]{1}[A-CEGHJ-NPR-TW-Z]{1}[0-9]{6}[A-DFM]{0,1}$</options>
  </customFieldDefinition>
  <customFieldDefinition>
    <id>1</id>
    <label>Lead Source</label>
    <type>List</type>
    <options>website;newsletter</options>
  </customFieldDefinition>
</customFieldDefinitions>{
  "customFieldDefinitions": {
    "customFieldDefinition": [
      {
        "id": "1",
        "tag": "Staff",
        "label": "NI Number",
        "type": "Text",
        "options": "^[A-CEGHJ-PR-TW-Z]{1}[A-CEGHJ-NPR-TW-Z]{1}[0-9]{6}[A-DFM]{0,1}$"
      },
      {
        "id": "1",
        "label": "Lead Source",
        "type": "List",
        "options": "website;newsletter"
      }
    ]
  }
}
Show as JSONShow as XML

Add, Update or Remove Custom Fields

Update some or all of the custom fields on a specific party, opportunity or case.

PUT /api/party/:id/customfields
PUT /api/opportuntity/:id/customfields
PUT /api/kase/:id/customfields

Request

To add or update a custom field specify the custom field label in the label element (for data-tags also specify the data-tag tag name in the tag element); then add the value to be loaded into custom field in the appropriate text, date or boolean field. For example to add or update the custom fields NI Number and Start Date for the data-tag Staff and set the custom field Send newsletter your xml might look like:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<customFields>
  <customField>
    <tag>Staff</tag>
    <label>NI Number</label>
    <text>12345678</text>
  </customField>
  <customField>
    <tag>Staff</tag>
    <label>Start Date</label>
    <date>2011-03-13T00:00:00Z</date>
  </customField>
  <customField>
    <label>Send newsletter</label>
    <boolean>true</boolean>
  </customField>
</customFields>{
  "customFields": {
    "customField": [
      {
        "tag": "Staff",
        "label": "NI Number",
        "text": "12345678"
      },
      {
        "tag": "Staff",
        "label": "Start Date",
        "date": "2011-03-13T00:00:00Z"
      },
      {
        "label": "Send newsletter",
        "boolean": "true"
      }
    ]
  }
}
Show as JSONShow as XML

To remove a custom field set the label and if appropriate tag element in your request but don’t include the text, date or boolean element in your request. For example to remove the NI Number custom field on the data-tag Staff.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<customFields>
  <customField>
    <tag>Staff</tag>
    <label>NI Number</label>
  </customField>
</customFields>{
  "customFields": {
    "customField": [
      {
        "tag": "Staff",
        "label": "NI Number"
      }
    ]
  }
}
Show as JSONShow as XML

In a single request it’s possible to mix and match additions, updates and deletions of custom fields. Custom field values that should be left unchanged should be excluded from the the request.

Response

HTTP/1.1 200 OK