API Field Rules – Folio Help Centre

When you are sending fields to Folio, by either updating or creating Folios, Entities or Contacts, Folio requires the data to be in a specific format.
This article outlines all of the field types and how the data should be formatted in your api mutations.
Each field value in the api is a response, so you will be passing a fieldResponses list to Folio which will contain all of the fields and their values.

Short Text

For a short text the value is put in “text”

fieldResponses: [
  {
    fieldId: "Field-428"
    text: "some short text"
  }
]

Long Text

For a long text the value is put in “text” - and can have HTML style tags

fieldResponses: [
  {
    fieldId: "Field-704"
    text: "folio <i>description</i>"
  }
]

Single/Multi Select Field

For single and multi select fields you will have a list of fieldAnswerResponses, which is made up of objects that should contain the fieldAnswerId.
The fieldAnswerId is found from the fieldAnswers query, explained here

My example below is a multi select, where the second answer has a freeform text option, so i put that inside of the object in freeformText.

For single selects you would just put the one object with the fieldAnswerId

fieldResponses: [
  {
    fieldId: "Field-430"
    fieldAnswerResponses: [
      {fieldAnswerId: "MDBGaWVsZEFuc3dlci0yNjc1"}
      {
        fieldAnswerId: "MDBGaWVsZEFuc3dlci0zMzIx"
        freeformText: "I do my taxes myself"
      }
    ]
  }
]

Numeric Field

For numeric fields the value is put in “numeric”

fieldResponses: [
  {
    fieldId: "Field-4493"
    numeric: 1234
  }
]

Date Field

For date fields you put the data in “date” in the format listed below -

fieldResponses: [
  {
    fieldId: "Field-4493"
    date: "2021-12-31"
  }
]

Time field

Time is stored in an object like below, where the hour and the minute is stored separately in 24 hours format

fieldResponses: [
  {
    fieldId: "Field-4493"
    time: {hour: 10, minute: 59}
  }
]

URL field

For URL field you put the data in “text”

fieldResponses: [
  {
    fieldId: "Field-4493"
    text: "http://www.kwelasolutions.com"
  }
]

Attachments Field

Attachment fields use the field response as outlined here

Address Field

Addresses are in an object, where each line is in its own part.

fieldResponses: [
  {
    fieldId: "Field-4493"
    address: {
      line1: "19 Regent St"
      suburb: "Rosefield"
      state: "NSW"
      postcode: "2100"
    }
  }
]

Email field

Email fields go in “text”

fieldResponses: [
  {
    fieldId: "Field-4493"
    text: "ben@example.com"
  }
]

Lookup Fields

Lookup Fields have a different setup compared to normal single/multi selects - These are the values you will get from the previous lookup requests, listed below is the setup for each lookup, you just need to change the “ids” to the relevant lookup and feed through the id’s you get from the lookup requests.

Business Unit

fieldResponses: [
  {
    fieldId: "Field-1256"
    businessUnitIds: [
      "BusinessUnit-2"
      "BusinessUnit-3"
    ]
  }
]

Entities

fieldResponses: [
  {
    fieldId: "Field-1256"
    entityIds: ["Entity-2"]
  }
]

Contacts

fieldResponses: [
  {
    fieldId: "Field-1256"
    contactIds: ["Contact-1"]
  }
]

Risk Classifications

fieldResponses: [
  {
    fieldId: "Field-1265"
    riskClassificationId: "RiskClassification-1"
  }
]

Users

fieldResponses: [
  {
    fieldId: "Field-1256"
    userIds: [
      "User-1"
      "User-2"
    ]
  }
]

Programs

fieldResponses: [
  {
    fieldId: "Field-1256"
    programIds: [
      "Program-1"
      "Program-2"
    ]
  }
]

Locations

fieldResponses: [
  {
    fieldId: "Field-1256"
    locationIds: [
      "Location-1"
      "Location-2"
    ]
  }
]

Risk Assessment

For the risk assessment we use an index of your likelihood, consequence, control rating and target risk. With the lowest rating being 1 and going up to the number of ratings you have.

fieldResponses: [
  {
    fieldId: "Field-1267"
    riskAssessment: {
      likelihoodIdx: 1
      consequenceIdx: 1
      controlRatingIdx: 2
      residualLikelihoodIdx: 2
      residualConsequenceIdx: 2
      targetRiskIdx: 3
      reviewStartDate: "2020-08-01"
    }
  }
]

Built In Fields

Built in fields do not have a field type as they are special fields. Detailed below is how you pase data to these built in fields.

title	Short text field with minimum 3 characters required.
description	Long text field.
business_units	Multi-select lookup on business units.
person_responsible	Multi-select lookup on users.
commencement_date	Date field
end_date	Date field
entities	Multi-select lookup on entities.
entity_contacts	Multi-select lookup on contacts.
service_providers	multi-select lookup on contacts.
risk_assessment	Risk Assessment on a folio, see Risk Assessment
risk_classification	Single-select lookup on risk classifications.
current_value	The sum of field Contract Value excl. GST and the values of all variations. It is a numeric field.
new_end_date	Date field.
lite_user	Boolean field.
access_rights	The access right of an entity/contact as a Lite User. It is a field of LiteUserAccessRightsEnum type.
name	Short text field.
abn	Short text field.
telephone	Short text field.
email	Short text field.
business_name	Short text field.
entity_category	Multi-select lookup on Entity Categories.

Articles in this section