An API Server app is able to query the API to retrieve Folio records and their fields.
A note about Folio Records if you have not used Folio before. Folio records are on a Folio Template, these templates are configurable and your administrators can add any number of custom fields to these templates which then can be filled in on each record. The base queries below are for the built in fields which most Folio records have (such as the Title, the Person Responsible or the Status).
For any custom fields you will need to use the API to query the template to find out which fields are on the template and then fill in the customFieldResponses object with those library field ids (see the example below where the custom field Inquiry Type comes from the customFieldResponses)
The queries will by default return 25 records per page, the pagination options that are explained here
For more information about custom fields see the custom fields article here
You can also filter the APAI results to only the records you need to see, see info about filtering here.
Below is an example of using the Folio query to get the Key, Person Responsible and Inquiry Type for all Folios with a publicLinkEmail from pete@example.com
Request {
folios(publicLinkEmail: "pete@example.com") {
nodes {
key
title
personResponsible {
nodes{
name
id
}
}
customFieldResponses(libraryFieldIds: ["MDBGaWVsZC05NDUz"], first:1) {
field {
name
}
... on SelectFieldResponse {
answers {
nodes {
fieldAnswer {
text
}
}
}
}
}
}
}
}
Response {
"data": {
"folios": {
"nodes": [
{
"title": "Example Folio Name",
"key": "FOL-12",
"personResponsible": {
"nodes":[
{
"name": "Jack",
"id": "MDBVc2VyLTE"
}
]
},
"customFieldResponses": [
{
"field": {
"name": "Inquiry Type"
},
"answers": {
"nodes":
[
{
"fieldAnswer": {
"text": "New Request"
}
}
]
}
}
]
}
]
}
}
}
For fields there are different behaviors for both custom fields and Built in fields, you are also able to filter on the built in fields.
Built in Fields Key The key of the folio, returns a string.
Request Response
{
folios {
nodes {
key
}
}
}{
"data": {
"folios": {
"nodes": [
{
"key": "SLA-1"
}
]
}
}
}
ID The ID of the folio, returns a string.
Request Response
{
folios {
nodes {
id
}
}
}{
"data": {
"folios": {
"nodes": [
{
"id": "MDBDb250cmFjdC0zNjQ2"
}
]
}
}
}
Title The Title of the folio, returns it as a string.
Request
Response
{
folios {
nodes {
title
}
}
}{
"data": {
"folios": {
"nodes": [
{
"title": "Example Contract with Example Corp"
}
]
}
}
}
Folio Template The Template of the folio, returns the templates name and ID
Request Response
{
folios {
nodes {
folioTemplate {
name
id
}
}
}
}{
"data": {
"folios": {
"nodes": [
{
"folioTemplate": {
"name": "Slack Notifications",
"id": "MDBDb250cmFjdFRlbXBsYXRlLTE0NQ"
}
}
]
}
}
}
Stage The Stage of the folio, returns the Stage Name, Display order (starting at 1) and the ID
Request Response
{
folios {
nodes {
stage {
name
displayOrder
id
}
}
}
}{
"data": {
"folios": {
"nodes": [
{
"stage": {
"name": "Management",
"displayOrder": 1,
"id": "MDBTdGFnZS01NDc"
}
}
]
}
}
}
Status Returns the status of the Folio as a String
Request Response
{
folios {
nodes {
status
}
}
}{
"data": {
"folios": {
"nodes": [
{
"status": "open"
}
]
}
}
}
Approval Status Returns the approval status of the Folio as a String
Request Response
{
folios {
nodes {
approvalStatus
}
}
}{
"data": {
"folios": {
"nodes": [
{
"approvalStatus": "requested"
}
]
}
}
}
Public Link Email Returns the Public Link Email of the Folio as a String (Will be empty for Folios not created through the public link
Request
Response
{
folios {
nodes {
publicLinkEmail
}
}
}{
"data": {
"folios": {
"nodes": [
{
"publicLinkEmail": "abc@abc.com"
}
]
}
}
}
Reminder Settings The Reminder Notification Settings for the Folio
Request
Response
{
folios {
nodes {
reminderSettings {
remindAfterRepeatOn
remindAfterRepeatType
remindBefore
remindBeforeNumber
remindBeforeRepeatOn
remindBeforeRepeatType
remindBeforeRepeated
remindBeforeUnit
}
}
}
}{
"data": {
"folios": {
"nodes": [
{
"reminderSettings": {
"remindAfterRepeatOn": [
1
],
"remindAfterRepeatType": "weekly",
"remindBefore": false,
"remindBeforeNumber": 5,
"remindBeforeRepeatOn": [
1
],
"remindBeforeRepeatType": "weekly",
"remindBeforeRepeated": false,
"remindBeforeUnit": "week"
}
}
]
}
}
}
Attachments The Attachments on the Folio, returns a list of attachments where each has an Title, ID and URL to download. Note you will need to log into Folio and have correct access rights to download the attachment.
Request
Response
{
folios {
nodes {
attachments {
nodes {
title
id
url
}
}
}
}
}{
"data": {
"folios": {
"nodes": [
{
"attachments": {
"nodes": [
{
"title": "my_file_name.pdf",
"id": "MDBBdHRhY2htZW50LTU5NA",
"url": "https://exampleCorp.sandbox.usefolio.com/attachments/1882/download"
}
]
}
}
]
}
}
}
Tags Returns the tags of the Folio, as a list of strings.
Request
Response
{
folios {
nodes {
tags
}
}
}{
"data": {
"folios": {
"nodes": [
{
"tags": [“one”]
}
]
}
}
}
Created At, Updated At, Published at, Closed at Returns the Datetime of the four metadata fields.
Request
Response
{
folios {
nodes {
createdAt
updatedAt
publishedAt
closedAt
}
}
}{
"data": {
"folios": {
"nodes": [
{
"createdAt": "2019-12-02T08:33:32+11:00",
"updatedAt": "2019-12-02T08:33:32+11:00",
"publishedAt": "2019-12-02T08:33:32+11:00",
"closedAt": "2019-12-02T08:33:32+11:00"
}
]
}
}
}
Created by, Updated by, Published by, Closed by Returns the id, name and email of the user for the four metadata fields.
Request
Response
{
folios {
nodes {
createdBy {
id
name
email
}
updatedBy{
id
name
email
}
publishedBy{
id
name
email
}
closedBy{
id
name
email
}
}
}
}{
"data": {
"folios": {
"nodes": [
{
"createdBy": {
"id": "MDBVc2VyLTE",
"name": "Jack",
"email": "jack@kwelasolutions.com"
},
"updatedBy": {
"id": "MDBVc2VyLTE",
"name": "Jack",
"email": "jack@kwelasolutions.com"
},
"publishedBy": {
"id": "MDBVc2VyLTE",
"name": "Jack",
"email": "jack@kwelasolutions.com"
},
"closedBy": {
"id": "MDBVc2VyLTE",
"name": "Jack",
"email": "jack@kwelasolutions.com"
}
}
]
}
}
}
Person Responsible Returns the Name, id and email of the Person Responsible
Request
Response
{
folios {
nodes {
personResponsible {
nodes{
name
id
}
}
}
}
}{
"data": {
"folios": {
"nodes": [
{
"personResponsible": {
"nodes":[
{
"name": "Jack",
"id": "MDBVc2VyLTE"
}
]
}
}
]
}
}
}
Business units Returns the id and title of the business unit
Request
Response
{
folios {
nodes {
businessUnits{
nodes{
title
id
}
}
}
}
}{
"data": {
"folios": {
"nodes": [
{
"businessUnits": {
"nodes":[
{
"id": "MDBCdXNpbmVzc1VuaXQtMjA",
"title": "Finance"
}
]
}
}
]
}
}
}
Current value Returns the current value as a number
Request
Response
{
folios {
nodes {
currentValue
}
}
}{
"data": {
"folios": {
"nodes": [
{
"currentValue": 0
}
]
}
}
}
Description
Request
Response
{
folios {
nodes {
description
}
}
}{
"data": {
"folios": {
"nodes": [
{
"description": “lorem ipsum”
}
]
}
}
}
CommencementDate
Request
Response
{
folios {
nodes {
commencementDate
}
}
}{
"data": {
"folios": {
"nodes": [
{
"commencementDate": "2019-09-29"
}
]
}
}
}
EndDate
Request
Response
{
folios {
nodes {
endDate
}
}
}{
"data": {
"folios": {
"nodes": [
{
"endDate": "2019-09-29"
}
]
}
}
}
Entities Returns the Name, id and key of the entities on the Folio
Request
Response
{
folios {
nodes {
businessUnits{
nodes{
name
id
key
}
}
}
}
}{
"data": {
"folios": {
"nodes": [
{
"entities": {
"nodes":[
{
"name": "Newt",
"id": "MDBFbnRpdHktOQ",
"key": "ENT-9"
},
{
"name": "Brian",
"id": "MDBFbnRpdHktNDA",
"key": "ENT-40"
}
]
}
}
]
}
}
}
Entity contacts Returns the Name and Id of the Entity Contacts on the Folio
Request
Response
{
folios {
nodes {
entityContacts{ nodes{ name id}}
}
}
}{
"data": {
"folios": {
"nodes": [
{
"entityContacts":
"nodes":[
{
"name": "Newt",
"id": "MDBDb250YWN0LTg"
}
]
}
}
]
}
}
}
Service providers Returns the Name and Id of the Service Providers on the Folio
Request
Response
{
folios {
nodes {
serviceProviders{nodes{name id}}
}
}
}{
"data": {
"folios": {
"nodes": [
{
"serviceProviders": {
"nodes":[
{
"name": "Newt",
"id": "MDBDb250YWN0LTg"
}
]
}
}
]
}
}
}
Risk The riskAssessment contains everything you’d need when extracting risks using the api, in the below example i have pulled every part of the risk assessment out
Request
Response
{
folios {
nodes {
riskAssessment {
consequence {
definition
displayOrder
name
}
controlRating {
definition
displayOrder
name
}
firstReviewDate
inherentRisk {
color
definition
displayOrder
name
}
likelihood {
definition
displayOrder
name
}
nextReviewDate
residualConsequence{
definition
displayOrder
name
}
residualLikelihood{
definition
displayOrder
name
}
residualRisk {
color
definition
displayOrder
name
}
reviewRepeatBy
reviewRepeatEndDate
reviewRepeatEvery
reviewRepeatOn
reviewRepeatBy
reviewRepeated
reviewRequired
riskMovement
targetRisk {
color
definition
displayOrder
name
}
}
}
}
}{
"data": {
"folios": {
"nodes": [
{
"riskAssessment": {
"firstReviewDate": null,
"nextReviewDate": null,
"residualConsequence": null,
"residualLikelihood": null,
"reviewRepeatBy": "day_of_month",
"reviewRepeatEndDate": null,
"reviewRepeatEvery": 1,
"reviewRepeatOn": [
1
],
"reviewRepeated": false,
"reviewRequired": false,
"riskMovement": 0,
"consequence": {
"definition": "... ",
"displayOrder": 5,
"name": "Catastrophic"
},
"controlRating": {
"definition": "...",
"displayOrder": 1,
"name": "Non-existent"
},
"inherentRisk": {
"color": "#7bd148",
"definition": null,
"displayOrder": 2,
"name": "Moderate"
},
"likelihood": {
"definition": "...",
"displayOrder": 1,
"name": "Rare"
},
"residualRisk": {
"color": "#7bd148",
"definition": "...",
"displayOrder": 2,
"name": "Moderate"
},
"targetRisk": {
"color": "#17a865",
"definition": "...",
"displayOrder": 1,
"name": "Low"
}
}
}
]
}
}
}
Risk classification Returns the Title, Definition and Impact of the Risk Classifications for the folio
Request Response
{
folios {
nodes {
riskClassification {
title
definition
impact
}
}
}
}{
"data": {
"folios": {
"nodes": [
{
"riskClassification": null
},
{
"riskClassification": {
"title": "Seasonality",
"definition": null,
"impact": null
}
},
{
"riskClassification": {
"title": "Environment",
"definition": null,
"impact": null
}
},
]
}
}
}
Linked Folios Returns all of the folios linked to the Folio as a list. Each item contains the relationship and the title and key for the linked folio.
Request Response
{
folios {
nodes {
folioLinks {
nodes{
relationship
folio {
key
title
}
}
}
}
}
}{
"data": {
"folios": {
"nodes": [
{
"folioLinks": {
"nodes": [
{
"relationship": "is_replaced_by",
"folio": {
"title": "Example Folio",
"key": "DIS-1"
}
}
]
}
}
]
}
}
}
