A custom-defined field is a field that can be added independent of a Pure release. You can read more about custom-defined fields and the process for getting custom-defined fields added to your Pure in the general custom-defined fields documentation.

Custom-defined fields are supported on a subset of the content types available in the Pure API, such as Person. A content type with support for custom-defined fields has a customDefinedFields field that maps from custom-defined field "property name" to a CustomDefinedField object. You access the value of a specific custom-defined field using the value field of the relevant CustomDefinedField object.

The specific type of CustomDefinedField object corresponds to the type of custom-defined field:

Reading

Custom-defined field values are automatically fetched alongside regular fields of content; fetching a content item of a content type that supports custom-defined fields will also fetch values of all custom-defined fields of the content type.

Reading values from custom-defined fields follows the general rules for content access though the API in the case of both regular and sensitive fields:

The customDefinedFields map is always populated with the full set of custom-defined fields that the API key allows access to, even ones where the current content item does not currently specify a value. If a custom-defined field was added after a content item was last saved then its customDefinedFields map will contain an entry with a CustomDefinedField object without a value.

https://{your Pure hostname}/ws/api/persons/29492640-5030-4843-91c1-7d85ca997749

{
  "pureId": 417899,
  "uuid": "29492640-5030-4843-91c1-7d85ca997749",
  ...
  "customDefinedFields": {
    "happy": {
      "typeDiscriminator": "Boolean"
    },
    "reason-for-happiness": {
      "typeDiscriminator": "String",
      "value": "Not considered, yet"
    },
   }
  ...
}

Writing

Custom-defined field values are updated alongside regular fields of content; updates to customDefinedFields will be saved when a content item is created or updated. Only modifications to entries present in the customDefinedFields map will have an effect. Removing an entry from the customDefinedFields map will have no effect.

Writing custom-defined fields values follows the general rules for content access though the API in the case of both regular and sensitive fields:

Custom-defined field values are specified on a new content item by adding entries to its customDefinedFields map with a key corresponding to the "property name" of each custom-defined field you want to specify a value for. You must specify a CustomDefinedField map value that fits the type of each field; if the field is boolean-based you must add a map entry with a CustomDefinedFieldBoolean object, etc.

Updating custom-defined field values is a three step process:

Fetch existing Pure API model object to manipulate its customDefinedFields map.
 

https://{your Pure hostname}/ws/api/persons/29492640-5030-4843-91c1-7d85ca997749

{
  "pureId": 417899,
  "uuid": "29492640-5030-4843-91c1-7d85ca997749",
  ...
  "customDefinedFields": {
    "happy": {
      "typeDiscriminator": "Boolean"
    },
    "reason-for-happiness": {
      "typeDiscriminator": "String",
      "value": "Not considered, yet"
    },
   }
  ...
}

Modify the customDefinedFields map to specify a value for the 'happy' field and change the value of the 'reason-for-happiness' field.
 

Submit the created/updated Pure API model object to the relevant endpoint, such as /persons.
 

https://{your Pure hostname}/ws/api/persons/29492640-5030-4843-91c1-7d85ca997749

{
  "pureId": 417899,
  "uuid": "29492640-5030-4843-91c1-7d85ca997749",
  ...
  "customDefinedFields": {
    "happy": {
      "typeDiscriminator": "Boolean",
      "value": true
    },
    "reason-for-happiness": {
      "typeDiscriminator": "String",
      "value": "Great friends"
    },
   }
  ...
}

{
  "pureId": 417899,
  "uuid": "29492640-5030-4843-91c1-7d85ca997749",
  ...
  "customDefinedFields": {
    "happy": {
      "typeDiscriminator": "Boolean",
       "value": true 
    },
    "reason-for-happiness": {
      "typeDiscriminator": "String",
      "value": "Great friends"
    },
   }
  ...
}

You can remove a custom-defined field value by specifying a CustomDefinedField object with no value. Re-fetching the content item will then include a map entry for the field where the corresponding CustomDefinedField object has no value.