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.

Resource URI

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

Examples

• URI for a Contact: /api/2012-02-01/auth/resources/contacts/99372/customfields/
• URI for an Organisation: /api/2012-02-01/auth/resources/organisations/3264/customfields/
• URI for a Registration: /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.

<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.

Related resource links

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. 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 unspecified, missing or null 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

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>

HTTP POST

Not supported.

HTTP PUT

Performs an update of a given 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. This operation should always be executed using a modified instance from a previous HTTP GET request.

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).

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 DELETE

Not supported.

To delete the value for a specific field, execute a HTTP PUT with the details of that field omitted.

HTTP PATCH

Performs a partial update of custom fields by replacing parts of the representation with data from the request. Note that our PATCH implementation follows the draft RFC 5261 standard. 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 or is invalid according to our implementation of RFC 5261.
409 Conflict	Resource could not be updated because it contains values that conflict with those on the server.

Example 1

Update the value of the 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

Update the value of the 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>