Arlo

REST Auth API: CustomFields

Custom fields represent unstructured user-defined data that can be associated with entities. Each entity can have a collection of typed fields, with the metadata for all available fields being described by the ResourceDescription for that entity.

A given field is defined by a name, a structured value (such as a string, integer or date value), plus a reference to the FieldDescription metadata about that field which can be used to retrieve additional details about its configuration such as its display label and supported values.

This resource is always accessed as a subresource of an existing entity and supports retrieval of field values and updating existing field values.

Common tasks

Finding available custom fields

Before adding a new custom field value to an entity, you need to know which custom fields are available for that resource type. Available fields are configured at the platform level.

Each field is assigned a unique FieldDescription GUID that you need when adding a <Field> element with a value to an entity. For example, it is used in the <Link title="FieldDescription"> element in PATCH Example 3 (adding a new field).

Each resource type that supports custom fields exposes a /describe/ endpoint that returns its ResourceDescription, including the list of available custom fields and their corresponding FieldDescription references. See the ResourceDescription page for full details on the response format.

Resource Describe endpoint URI (custom fields)
Contact /api/2012-02-01/auth/resources/contacts/describe/customfields
Organisation /api/2012-02-01/auth/resources/organisations/describe/customfields
Registration /api/2012-02-01/auth/resources/registrations/describe/customfields

Resource URI

For a given resource type and ID, the values for any custom fields on that record can be accessed at the following URI:

/api/2012-02-01/auth/resources/{ResourceType}/{ResourceID}/customfields/

Examples

  • URI for a Contact record: /api/2012-02-01/auth/resources/contacts/99372/customfields/
  • URI for an Organisation record: /api/2012-02-01/auth/resources/organisations/3264/customfields/
  • URI for a Registration record: /api/2012-02-01/auth/resources/registrations/223901/customfields/

General structure

This resource is represented by a list of Field elements, each representing a different custom field attached to the owner entity.

Only fields that have a defined value on that record are returned. The platform may define more custom fields that aren't currently used by that record (have an undefined value), and these will not be returned until they are assigned a value.

<CustomFields>
  <Field>
    <Name>TaxCode</Name>
    <Value>
      <String>7900-0023-AF01</String>
    </Value>
    <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/FieldDescription" type="application/xml" title="FieldDescription" href="https://demo.arlo.co/api/2012-02-01/auth/resources/fielddescriptions/d59c69b8-2259-4830-afb2-524930bc27c8/"/>
  </Field>
  <Field>
    <Name>FavouriteGenres</Name>
    <Value>
      <StringArray>
        <String>Thriller</String>
        <String>Science fiction</String>
        <String>Biography</String>
      </StringArray>
    </Value>
    <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/FieldDescription" type="application/xml" title="FieldDescription" href="https://demo.arlo.co/api/2012-02-01/auth/resources/fielddescriptions/93ea3aa9-74b4-4a68-900d-bab07a623b5b/"/>
  </Field>
  <Field>
    <Name>YearOfLastPromotion</Name>
    <Value>
      <Integer32>2012</Integer32>
    </Value>
    <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/FieldDescription" type="application/xml" title="FieldDescription" href="https://demo.arlo.co/api/2012-02-01/auth/resources/fielddescriptions/3de23667-2141-4390-89e4-ca172f6800a5/"/>
  </Field>
  <Field>
    <Name>LastContacted</Name>
    <Value>
      <Date>2015-01-27</Date>
    </Value>
    <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/FieldDescription" type="application/xml" title="FieldDescription" href="https://demo.arlo.co/api/2012-02-01/auth/resources/fielddescriptions/f4e23507-8841-2182-89e4-df1732680299Z"/>
  </Field>
  <Field>
    <Name>IsMember</Name>
    <Value>
      <Boolean>false</Boolean>
    </Value>
    <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/FieldDescription" type="application/xml" title="FieldDescription" href="https://demo.arlo.co/api/2012-02-01/auth/resources/fielddescriptions/340b2512-1846-45b7-aa06-eb5ef3dbd94e/"/>
  </Field>
  <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/14906/customfields/"/>
</CustomFields>

Resource properties

Property Description
Name The descriptive name of the field, copied from the underlying FieldDescription. This value is read-only.
Value An XML element that describes the value of the field, with a structure specific to the field type.
Link (title) Description
FieldDescription Reference to a FieldDescription resource describing the properties of the field, including its name, format and type.

Value element

The content of the Value element depends on the type of the field from its FieldDescription. The supported types with examples are covered in this section.

String value

Supports storage of up to 2048-character values.

<Value>
   <String>The quick brown fox jumps over the brown lazy dog.</String>
</Value>
Boolean value

Supports storage of boolean true or false values.

<Value>
   <Boolean>true</Boolean>
</Value>
StringArray value

Supports storage of multiple, ordered String values.

<Value>
    <StringArray>
        <String>Cat</String>
        <String>Dog</String>
        <String>Mouse</String>
    </StringArray>
</Value>
Integer32 value

Supports storage of 32-bit integer values.

<Value>
   <Integer32>1990</Integer32>
</Value>
Date value

Supports storage of date values in ISO 8601 format (YYYY-MM-DD).

<Value>
   <Date>1990-09-27</Date>
</Value>
(Null) value

Describes an empty value.

<Value />

HTTP GET

Returns a representation of all custom fields associated with an entity, including the properties and links above.

Optional parameters
Parameter Description
expand Expression referencing Link elements to expand when generating the response. See link expansion.
Example 1 - basic retrieval

Retrieve the custom fields and values for Contact record with ID 562.

GET /api/2012-02-01/auth/resources/contacts/562/customfields/

<CustomFields>
  <Field>
    <Name>TaxCode</Name>
    <Value>
      <String>7900-0023-AF01</String>
    </Value>
    <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/FieldDescription" type="application/xml" title="FieldDescription" href="https://demo.arlo.co/api/2012-02-01/auth/resources/fielddescriptions/d59c69b8-2259-4830-afb2-524930bc27c8/"/>
  </Field>
  <Field>
    <Name>FavouriteGenres</Name>
    <Value>
      <StringArray>
        <String>Thriller</String>
        <String>Science fiction</String>
        <String>Biography</String>
      </StringArray>
    </Value>
    <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/FieldDescription" type="application/xml" title="FieldDescription" href="https://demo.arlo.co/api/2012-02-01/auth/resources/fielddescriptions/93ea3aa9-74b4-4a68-900d-bab07a623b5b/"/>
  </Field>  
  <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/14906/customfields/"/>
</CustomFields>
Example 2 - with expanded FieldDescription

Retrieve the custom fields and values for Contact record with ID 562, with FieldDescription link expansion, showing a String value, a StringArray value, and a field with a blank value.

GET /api/2012-02-01/auth/resources/contacts/562/customfields/?expand=FieldDescription

<CustomFields>
  <Field>
    <Name>TaxCode</Name>
    <Value>
      <String>7900-0023-AF01</String>
    </Value>
    <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/FieldDescription" type="application/xml" title="FieldDescription" href="https://demo.arlo.co/api/2012-02-01/auth/resources/fielddescriptions/d59c69b8-2259-4830-afb2-524930bc27c8/">
      <FieldDescription>
        <FieldDescriptionID>d59c69b8-2259-4830-afb2-524930bc27c8</FieldDescriptionID>
        <Name>TaxCode</Name>
        <Label>Tax Code</Label>
        <Type>String</Type>
        <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/fielddescriptions/d59c69b8-2259-4830-afb2-524930bc27c8/"/>
      </FieldDescription>
    </Link>
  </Field>
  <Field>
    <Name>FavouriteGenres</Name>
    <Value>
      <StringArray>
        <String>Thriller</String>
        <String>Science fiction</String>
        <String>Biography</String>
      </StringArray>
    </Value>
    <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/FieldDescription" type="application/xml" title="FieldDescription" href="https://demo.arlo.co/api/2012-02-01/auth/resources/fielddescriptions/93ea3aa9-74b4-4a68-900d-bab07a623b5b/">
      <FieldDescription>
        <FieldDescriptionID>93ea3aa9-74b4-4a68-900d-bab07a623b5b</FieldDescriptionID>
        <Name>FavouriteGenres</Name>
        <Label>Favourite Genres</Label>
        <Type>StringArray</Type>
        <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/fielddescriptions/93ea3aa9-74b4-4a68-900d-bab07a623b5b/"/>
      </FieldDescription>
    </Link>
  </Field>
  <Field>
    <Name>IsMember</Name>
    <Value />
    <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/FieldDescription" type="application/xml" title="FieldDescription" href="https://demo.arlo.co/api/2012-02-01/auth/resources/fielddescriptions/340b2512-1846-45b7-aa06-eb5ef3dbd94e/">
      <FieldDescription>
        <FieldDescriptionID>340b2512-1846-45b7-aa06-eb5ef3dbd94e</FieldDescriptionID>
        <Name>IsMember</Name>
        <Label>Is Member</Label>
        <Type>Boolean</Type>
        <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/fielddescriptions/340b2512-1846-45b7-aa06-eb5ef3dbd94e/"/>
      </FieldDescription>
    </Link>
  </Field>
  <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/562/customfields/?expand=FieldDescription"/>
</CustomFields>

HTTP POST

Not supported.

HTTP PUT

Overwrites an entity's custom fields by replacing the entire representation with a new copy.

The submitted CustomFields representation must be complete. Any omitted fields will be deleted from the entity if they had previous values.

Ensure you always use HTTP PUT with a modified payload from a HTTP GET that includes the changes you need. Don't ever build a HTTP PUT payload from scratch as any extra elements you miss (such as those added in newer API releases your code doesn't handle) will be treated as explicit data deletion requests and may result in unintended data corruption.

To perform a partial update, use the HTTP PATCH method.

Response

See HTTP response status codes for a general overview of all possible API status codes. Common response codes for PUT operations are listed below.

Status Description
200 OK Resource was successfully updated.
400 Bad Request HTTP request body contains malformed or invalid parameters.
409 Conflict Resource could not be updated because it contains values that conflict with those on the server.
Example 1

Simple update of an existing contact's custom fields. The operation includes new values for two fields (TaxCode and FavouriteGenres). Values for all other custom fields will be cleared for this entity as they are not included in the payload.

PUT https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/562/customfields/ HTTP/1.1
Accept: application/xml
Accept-Encoding: gzip, deflate
Content-Type: application/xml
Content-Length: 1769

<CustomFields>
  <Field>
    <Name>TaxCode</Name>
    <Value>
      <String>7900-0023-AF01</String>
    </Value>
    <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/FieldDescription" type="application/xml" title="FieldDescription" href="https://demo.arlo.co/api/2012-02-01/auth/resources/fielddescriptions/d59c69b8-2259-4830-afb2-524930bc27c8/"/>
  </Field>
  <Field>
    <Name>FavouriteGenres</Name>
    <Value>
      <StringArray>
        <String>Thriller</String>
        <String>Science fiction</String>
        <String>Biography</String>
      </StringArray>
    </Value>
    <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/FieldDescription" type="application/xml" title="FieldDescription" href="https://demo.arlo.co/api/2012-02-01/auth/resources/fielddescriptions/93ea3aa9-74b4-4a68-900d-bab07a623b5b/"/>
  </Field>  
  <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/14906/customfields/"/>
</CustomFields>
Example 2

Update an existing contact's fields, setting two field values (TaxCode and FavouriteGenres) to have null values.

PUT https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/14906/customfields/ HTTP/1.1
Accept: application/xml
Accept-Encoding: gzip, deflate
Content-Type: application/xml
Content-Length: 1769

<CustomFields>
  <Field>
    <Name>TaxCode</Name>
    <Value />
    <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/FieldDescription" type="application/xml" title="FieldDescription" href="https://demo.arlo.co/api/2012-02-01/auth/resources/fielddescriptions/d59c69b8-2259-4830-afb2-524930bc27c8/"/>
  </Field>
  <Field>
    <Name>FavouriteGenres</Name>
    <Value />
    <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/FieldDescription" type="application/xml" title="FieldDescription" href="https://demo.arlo.co/api/2012-02-01/auth/resources/fielddescriptions/93ea3aa9-74b4-4a68-900d-bab07a623b5b/"/>
  </Field>  
  <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/14906/customfields/"/>
</CustomFields>

HTTP PATCH

Performs a partial update of custom fields by replacing parts of the representation with data from the request. See HTTP PATCH partial updates for a general guide to the diff document format, XPath selectors, and worked examples. Note that PATCH requests will be interpreted according to the RBAC permissions of the identity of the user on behalf of whom a request is being made.

Response

See HTTP response status codes for a general overview of all possible API status codes. Common response codes for PATCH operations are listed below.

Status Description
200 OK Resource was successfully updated.
400 Bad Request HTTP request body contains malformed or invalid parameters.
409 Conflict Resource could not be updated because it contains values that conflict with those on the server.
Example 1 - updating an existing field value

Update the value of an existing field TaxCode with a new String value.

PATCH https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/3123/customfields/ HTTP/1.1
Accept: application/xml
Accept-Encoding: gzip, deflate
Content-Type: application/xml
Content-Length: 103

<diff>
  <replace sel="CustomFields/Field[Name='TaxCode']/Value/String">
    <String>73-998-009-01A</String>
  </replace>
</diff>
Example 2 - clearing an existing field value

Update the value an existing field TaxCode and set it to have a null value.

PATCH https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/3123/customfields/ HTTP/1.1
Accept: application/xml
Accept-Encoding: gzip, deflate
Content-Type: application/xml
Content-Length: 103

<diff>
  <replace sel="CustomFields/Field[Name='TaxCode']/Value">
    <Value />
  </replace>
</diff>
Example 3 - multiple operations (adding a new field and updating existing fields)

A single PATCH request can contain multiple operations. This example combines three operations: updating the existing TaxCode field to Exempt, updating the existing MembershipType field to Annual, and adding a value for a new field IndustryCategory with a String value.

When adding a new field, the <Field> element must include a FieldDescription link that identifies the field by its GUID. To find the correct GUID, use the ResourceDescription for the entity you are updating to list the supported fields and their corresponding FieldDescription references.

PATCH https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/3123/customfields/ HTTP/1.1
Accept: application/xml
Accept-Encoding: gzip, deflate
Content-Type: application/xml
Content-Length: 681

<diff>
  <replace sel="CustomFields/Field[Name='TaxCode']/Value/String">
    <String>Exempt</String>
  </replace>
  <replace sel="CustomFields/Field[Name='MembershipType']/Value/String">
    <String>Annual</String>
  </replace>
  <add sel="CustomFields">
    <Field>
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/FieldDescription" type="application/xml" title="FieldDescription" href="https://demo.arlo.co/api/2012-02-01/auth/resources/fielddescriptions/7d925320-3662-49c1-b88e-efa86591a56f/"/>
      <Name>IndustryCategory</Name>
      <Value>
        <String>Retail</String>
      </Value>
    </Field>
  </add>
</diff>