Develop using the Custom Fields API

When creating a custom field, you can create associations with entities. You can also add custom fields to transactions and other entities by configuring the custom field definition ID while creating the transaction. You can create client or server apps from the ground up, or start with a common use case.

Read custom field definitions

Use appFoundationsCustomFieldDefinitions (query) in the Custom Fields GraphQL API to read custom fields. The output lists the custom fields along with data types and entities.

Create a custom field definition

Use appFoundationsCreateCustomFieldDefinition (mutation) in the Custom Fields API to create a custom field.

Update a custom field definition

Use appFoundationsUpdateCustomFieldDefinition (mutation) in the Custom Fields API to update a custom field.

Disable a custom field definition

Use appFoundationsUpdateCustomFieldDefinition (mutation) in the Custom Fields API to disable a custom field.

Create an entity with custom fields

These entities support custom fields: Customer, Vendor. Use the Accounting REST API to create a customer or vendor entity and send CustomField.DefinitionId with values from Step 1 below. This example creates a customer with custom fields.

Step 1: Create the custom field definition using appFoundationsCreateCustomFieldDefinition (mutation) in the Custom Fields GraphQL API.

Step 2: Use the Accounting REST API resource to create a customer with a custom field.

Sample Customer with Custom Field definition

Request

1
2
3
4
5
6
7
8
9
  {
      "DisplayName": "Customer-01",
      "CustomField": [
          {
              "DefinitionId": "540344",
              "StringValue": "CF-CustomerType"
          }
      ]
  }
Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
  {
      "Customer": {
          "Taxable": false,
          "Job": false,
          "BillWithParent": false,
          "Balance": 0,
          "BalanceWithJobs": 0,
          "CurrencyRef": {
              "value": "USD",
              "name": "United States Dollar"
          },
          "PreferredDeliveryMethod": "None",
          "IsProject": false,
          "domain": "QBO",
          "sparse": false,
          "Id": "4",
          "SyncToken": "0",
          "MetaData": {
              "CreateTime": "2024-06-29T19:12:52-07:00",
              "LastUpdatedTime": "2024-06-29T19:12:52-07:00"
          },
          "CustomField": [
              {
                 "DefinitionId": "540344",
                  "Name": "cf-05",
                  "Type": "StringType",
                  "StringValue": "CF-CustomerType"
              }
          ],
          "FullyQualifiedName": "Customer-01",
          "DisplayName": "Customer-01",
          "PrintOnCheckName": "Customer-01",
          "Active": true
      },
      "time": "2024-06-29T19:12:51.593-07:00"
  }
Test with Postman

To test your app, use Postman. Fork our official collection specifically for the Custom Fields API here. For more information, see Set up and test queries in Postman.