Articles in this section

API Creating & Updating Entities and Contacts

Avatar
Jack Davenport
  • Updated
Follow

The mutations you use for Creating & Updating in Folio are slightly different but all use the same structure for the fields and values.

The fieldResponses is an array of objects where each object represents a field. The object contains the field’s id and the value that will be stored in that field.

So for example if you were updating 3 fields on a Entity or Contact you would have three objects in the array - each having the corresponding fieldid and content in the specified format for that field type. 

An example of the array for creating a Folio is shown below

fieldResponses: [{fieldId: "MDBGaWVsZC0xNDI", text: "Some Example Text"}]

Another example below shows the array but the field i am using ia a multi select, so my values for the field are in an array called “fieldAnswerResponses” , where i use the fieldAnswerId to select the answers and on my second one have set the freeFormText for that answer to “I do my taxes myself”. 

fieldResponses: [
 {
   fieldId: "MDBGaWVsZC00MzA"
   fieldAnswerResponses: [
     {fieldAnswerId: "MDBGaWVsZEFuc3dlci05N"}
     {
       fieldAnswerId: "MDBGaWVsZEFuc3dlci05OQ",
       freeFormText: "I do my taxes myself"
     }
   ]
 }
]

mceclip0.png

The rules for how you pass values for each field type are explained here

To get the fieldId for a field you use the entityFields or contactFields query explained here

Creating Records

Creating an Entity 

To create a new Entity you will use the createEntity mutation to pass the values you want for the new Entity. 

You can get the fields on the entity by using the entityFields query, see Getting FieldsID's for more information

Now that you have the fields on the Entity we can start making the mutation to create the Entity. 

Below is an example of how to make a new Entity with some basic fields

Request

 Response 
mutation {
  createEntity(
    input: {fieldResponses: [
      { 
         fieldId: "MDBGaWVsZC0zMA", 
         text: "Sample Entity"
      },
      {
          fieldId: "MDBGaWVsZODgw", 
          entityCategoryId: "MDByeS0x"
      },
      {
          fieldId: "MDBGaWVsZC0yNw", 
          boolean: false
      }
     ]
    }
  ) {
    data {
      key
      name
    }
    errors {
      extensions {
        fieldName
      }
      message
    }
  }
}
 
{
  "data": {
    "createEntity": {
      "data": {
        "key": "ENT-45",
        "name": "Sample Entity"
      },
      "errors": null
    }
  }
}

Creating an Contact

To create a new Contact you will use the createContact mutation to pass the values you want for the new contact along with the id of the Entity that the contact will be created on.

To get the ID of the Entity you can use the entities query - once you have the ID of the entity that you want to create the contact on you can use the contactFields query to get the fields you are able to use on the Contact, see Getting FieldsID's for information about how to get the Field ID’s

Now that you have the fields on the Contact we can start making the mutation to create the Contact . The createContact  mutation uses an array of fieldResponses - See the top of this article for more info about the field responses array. 

Below is an example of how to make a new Contact with a name, phone number and no lite user

Request

 Response 
mutation {
  createContact(
    input: {entityId: "MDBFbnRpdHktMzI",    
     fieldResponses: [
      {fieldId: "MDBGaWVsZC0zOQ", 
          text: "An Example Contact"}, 
      {fieldId: "MDBGaWVsZC00MA", 
           numeric: 491570006}, 
      {fieldId: "MDBGaWVsZC0zNw", 
             boolean: false}
     ]
    }
  ) {
    data {
      name
      id
    }
    errors {
      extensions {
        fieldName
      }
      message
    }
  }
}
 
{
  "data": {
    "createContact": {
      "data": {
        "name": "An Example Contact",
        "id": "MDBDb250YWN0LTIw"
      },
      "errors": null
    }
  }
}

Updating Records

A Server app will let you update Entities & Contacts that the executed as user is able to update within Folio. 

After the mutation is run the fields will now reflect the values you specified on the mutation Except for multi selects where the existing answers will remain and any new answers will be selected alongside the existing answers. 

Updating an Entity

Updating a folio uses the updateEntities mutation. The Update mutation requires the id of the Entity you are going to update (You can get this id from the entities query)

An Example mutation is shown below

mutation {
  updateEntity(
    input: {entityId: "MDBFbnRpdHktMzI", fieldResponses: [
      {fieldId: "MDBGaWVsZC0zMA", text: "New name for the entity"}
     ]
    }
  ) {
    data {
      key
      name
    }
    errors {
      extensions {
        fieldName
      }
      message
    }
  }
}

Updating an Contact

Updating a folio uses the updateContacts mutation. The Update mutation requires the id of the Contact you are going to update (You can get this id from the contacts query)

An Example mutation is shown below

mutation {
  updateContact(
    input: {contactId: "MDBDb250YWN0LTIw", 
       fieldResponses: [
          {fieldId: "MDBGaWVsZC00MQ", text: "Bridge@example.com"}
       ]
    }
  ) {
    data {
      id
      name
    }
    errors {
      extensions {
        fieldName
      }
      message
    }
  }
}

Related articles