Custom Fields endpoints

The Customfields endpoints enable you to retrieve, update or delete already created custom fields in a Gtmhub account, as well as create new ones. Once created a custom field automatically appears in the UI for all the types it's been defined to apply to.

When you create a custom field in Gtmhub you specify its label. This is what identifies the custom filed in the UI. When working with custom fields programaptically though, you must use the custom field name. The name is automatically generated and is not visible in the UI.

To get the programmatic name of a custom filed you must make a call to the getCustomFieldsv2 endpoint. It will return all custom fields defined in your Gtmhub account and the response contains the custom filed label as well as its name. Use the name value when you want to work with this custom field via API (e.g. set its value to something).

🔗
get
/customFields
Loads all custom fields using filter, sort and projection expressions coming from the request body
Parameters
NameTypeDescription
Expected response codes
200customFieldsResponse
401unauthorized

curl -X GET 'https://app.gtmhub.com/api/v2/customFields' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer {token}' \

var settings = { "url": "https://app.gtmhub.com/api/v2/customFields", "method": "GET", "timeout": 0, "headers": { "Content-Type": "application/json", "Accept": "application/json", "Authorization": "Bearer {token}",
}
}; $.ajax(settings).done(function (response) { console.log(response); });
 NOTE: You must install the module requests.
In a terminal window do: pip install requests



import requests, json

headers = { "Authorization" : "Bearer {token}", "gtmhub-accountId" : "{accountId}", "Content-Type" : "application/json" };

url = "https://app.gtmhub.com/api/v2/customFields"



requests.get(url, headers = headers)
{
    "items": [
        {
            "_id": "string value",
            "accountId": "string value",
            "dateCreated": "string value",
            "description": "string value",
            "filterable": false,
            "isPrivate": false,
            "label": "string value",
            "lastModified": "string value",
            "name": "string value",
            "operationalType": "string value",
            "orderId": 2,
            "pluginVersionId": "string value",
            "targetIds": [
                "string value 1",
                "string value 2"
            ],
            "targetTypes": [
                "string value 1",
                "string value 2"
            ],
            "tooltip": "string value",
            "type": "string value",
            "visualizationKind": "string value"
        }
    ],
    "targetTypes": [
        "string value 1",
        "string value 2"
    ],
    "totalCount": 2
}
🔗
get
/customFields/supported-types
Gets a list of the target types in Gtmhub you can add custom fields to.
Parameters
NameTypeDescription
gtmhub-accountId
*
stringSpecifies the ID of the gtmhub account.
expected in header, sample value:
5be26318e5274a0007f17f61
Expected response codes
200customFieldsTypesResponse
401unauthorized

curl -X GET 'https://app.gtmhub.com/api/v1/customFields/supported-types' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer {token}' \
-H 'gtmhub-accountId: 5be26318e5274a0007f17f61' \

var settings = { "url": "https://app.gtmhub.com/api/v1/customFields/supported-types", "method": "GET", "timeout": 0, "headers": { "Content-Type": "application/json", "Accept": "application/json", "Authorization": "Bearer {token}",
"gtmhub-accountId": "5be26318e5274a0007f17f61",
}
}; $.ajax(settings).done(function (response) { console.log(response); });
 NOTE: You must install the module requests.
In a terminal window do: pip install requests



import requests, json

headers = { "Authorization" : "Bearer {token}", "gtmhub-accountId" : "{accountId}", "Content-Type" : "application/json" };

url = "https://app.gtmhub.com/api/v1/customFields/supported-types"



requests.get(url, headers = headers)
{
    "items": [
        "string value 1",
        "string value 2"
    ],
    "totalCount": 2
}
🔗
get
/customFields/{id}
Gets a single custom field based on the provided id.
Parameters
NameTypeDescription
gtmhub-accountId
*
stringSpecifies the ID of the gtmhub account.
expected in header, sample value:
5be26318e5274a0007f17f61
id
*
stringSpecifies the ID of the custom field.
expected in path, sample value:
5be26318e5274a0007f17f61
Expected response codes
200customFieldResponse
401unauthorized

curl -X GET 'https://app.gtmhub.com/api/v1/customFields/{id}' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer {token}' \
-H 'gtmhub-accountId: 5be26318e5274a0007f17f61' \

var settings = { "url": "https://app.gtmhub.com/api/v1/customFields/{id}", "method": "GET", "timeout": 0, "headers": { "Content-Type": "application/json", "Accept": "application/json", "Authorization": "Bearer {token}",
"gtmhub-accountId": "5be26318e5274a0007f17f61",
}
}; $.ajax(settings).done(function (response) { console.log(response); });
 NOTE: You must install the module requests.
In a terminal window do: pip install requests



import requests, json

headers = { "Authorization" : "Bearer {token}", "gtmhub-accountId" : "{accountId}", "Content-Type" : "application/json" };

url = "https://app.gtmhub.com/api/v1/customFields/{id}"



requests.get(url, headers = headers)
{
    "_id": "string value",
    "accountId": "string value",
    "dateCreated": "string value",
    "description": "string value",
    "filterable": false,
    "isPrivate": false,
    "label": "string value",
    "lastModified": "string value",
    "name": "string value",
    "operationalType": "string value",
    "orderId": 2,
    "pluginVersionId": "string value",
    "targetIds": [
        "string value 1",
        "string value 2"
    ],
    "targetTypes": [
        "string value 1",
        "string value 2"
    ],
    "tooltip": "string value",
    "type": "string value",
    "visualizationKind": "string value"
}
🔗
post
/customFields
Creates a custom field.
Parameters
NameTypeDescription
gtmhub-accountId
*
stringSpecifies the ID of the gtmhub account.
expected in header, sample value:
5be26318e5274a0007f17f61
customField
*
objectThe object representing a custom field. The 'name' field is used as a key for storage so it should be from 4 to 14 symbols, start with a lowercase letter and only contain letters, numbers and _. The 'type' field currently supports: string, number, bool, date, array:[any of the aforementioned types] The 'visualizationKind' field contains the name of the UI widget/component that will manage the custom field data. A good practice is to follow a naming convention for prefixing the visualizationKind like: gtmhub.textbox, gtmhub.textarea, gtmhub.number, gtmhub.checkbox, gtmhub.checkboxes, gtmhub.radiobuttons, gtmhub.address etc. A 'filterable' field can be used for filtering queries. The 'targetTypes' field lists type names that this custom field applies to. To get a list of all system types that support adding a custom field to, use the /customFields/supported-types endpoint. The 'settings' field is used to add predefined values, validation etc. Once created a custom field 'name' and 'type' can't be changed
expected in body, sample value:
{
    "_id": "string value",
    "description": "string value",
    "filterable": false,
    "label": "string value",
    "name": "string value",
    "operationalType": "string value",
    "orderId": 2,
    "targetIds": [
        "string value 1",
        "string value 2"
    ],
    "targetTypes": [
        "string value 1",
        "string value 2"
    ],
    "tooltip": "string value",
    "type": "string value",
    "visualizationKind": "string value"
}
Expected response codes
201customFieldResponse
401unauthorized

curl -X POST 'https://app.gtmhub.com/api/v1/customFields' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer {token}' \
-H 'gtmhub-accountId: 5be26318e5274a0007f17f61' \
-d '{"_id":"string value","description":"string value","filterable":false,"label":"string value","name":"string value","operationalType":"string value","orderId":2,"targetIds":["string value 1","string value 2"],"targetTypes":["string value 1","string value 2"],"tooltip":"string value","type":"string value","visualizationKind":"string value"}'

var body ={ "_id": "string value", "description": "string value", "filterable": false, "label": "string value", "name": "string value", "operationalType": "string value", "orderId": 2, "targetIds": [ "string value 1", "string value 2" ], "targetTypes": [ "string value 1", "string value 2" ], "tooltip": "string value", "type": "string value", "visualizationKind": "string value" };

var settings = { "url": "https://app.gtmhub.com/api/v1/customFields", "method": "POST", "timeout": 0, "headers": { "Content-Type": "application/json", "Accept": "application/json", "Authorization": "Bearer {token}",
"gtmhub-accountId": "5be26318e5274a0007f17f61",
},
"data": body
}; $.ajax(settings).done(function (response) { console.log(response); });
 NOTE: You must install the module requests.
In a terminal window do: pip install requests



import requests, json

headers = { "Authorization" : "Bearer {token}", "gtmhub-accountId" : "{accountId}", "Content-Type" : "application/json" };

url = "https://app.gtmhub.com/api/v1/customFields"

body = { "_id": "string value", "description": "string value", "filterable": false, "label": "string value", "name": "string value", "operationalType": "string value", "orderId": 2, "targetIds": [ "string value 1", "string value 2" ], "targetTypes": [ "string value 1", "string value 2" ], "tooltip": "string value", "type": "string value", "visualizationKind": "string value" };

requests.post(url, data=json.dumps(body), headers = headers)
{
    "_id": "string value",
    "accountId": "string value",
    "dateCreated": "string value",
    "description": "string value",
    "filterable": false,
    "isPrivate": false,
    "label": "string value",
    "lastModified": "string value",
    "name": "string value",
    "operationalType": "string value",
    "orderId": 2,
    "pluginVersionId": "string value",
    "targetIds": [
        "string value 1",
        "string value 2"
    ],
    "targetTypes": [
        "string value 1",
        "string value 2"
    ],
    "tooltip": "string value",
    "type": "string value",
    "visualizationKind": "string value"
}
🔗
put
/customFields/{id}
Updates the specified custom field. Note that custom field name and type can't be changed.
Parameters
NameTypeDescription
gtmhub-accountId
*
stringSpecifies the ID of the gtmhub account.
expected in header, sample value:
5be26318e5274a0007f17f61
id
*
stringSpecifies the ID of the custom field.
expected in path, sample value:
5be26318e5274a0007f17f61
customField
*
objectThe object representing a custom field. The 'name' field is used as a key for storage so it should be from 4 to 14 symbols, start with a lowercase letter and only contain letters, numbers and _. The 'type' field currently supports: string, number, bool, date, array:[any of the aforementioned types] The 'visualizationKind' field contains the name of the UI widget/component that will manage the custom field data. A good practice is to follow a naming convention for prefixing the visualizationKind like: gtmhub.textbox, gtmhub.textarea, gtmhub.number, gtmhub.checkbox, gtmhub.checkboxes, gtmhub.radiobuttons, gtmhub.address etc. A 'filterable' field can be used for filtering queries. The 'targetTypes' field lists type names that this custom field applies to. To get a list of all system types that support adding a custom field to, use the /customFields/supported-types endpoint. The 'settings' field is used to add predefined values, validation etc. Once created a custom field 'name' and 'type' can't be changed
expected in body, sample value:
{
    "_id": "string value",
    "description": "string value",
    "filterable": false,
    "label": "string value",
    "name": "string value",
    "operationalType": "string value",
    "orderId": 2,
    "targetIds": [
        "string value 1",
        "string value 2"
    ],
    "targetTypes": [
        "string value 1",
        "string value 2"
    ],
    "tooltip": "string value",
    "type": "string value",
    "visualizationKind": "string value"
}
Expected response codes
200customFieldResponse
401unauthorized

curl -X PUT 'https://app.gtmhub.com/api/v1/customFields/{id}' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer {token}' \
-H 'gtmhub-accountId: 5be26318e5274a0007f17f61' \
-d '{"_id":"string value","description":"string value","filterable":false,"label":"string value","name":"string value","operationalType":"string value","orderId":2,"targetIds":["string value 1","string value 2"],"targetTypes":["string value 1","string value 2"],"tooltip":"string value","type":"string value","visualizationKind":"string value"}'

var body ={ "_id": "string value", "description": "string value", "filterable": false, "label": "string value", "name": "string value", "operationalType": "string value", "orderId": 2, "targetIds": [ "string value 1", "string value 2" ], "targetTypes": [ "string value 1", "string value 2" ], "tooltip": "string value", "type": "string value", "visualizationKind": "string value" };

var settings = { "url": "https://app.gtmhub.com/api/v1/customFields/{id}", "method": "PUT", "timeout": 0, "headers": { "Content-Type": "application/json", "Accept": "application/json", "Authorization": "Bearer {token}",
"gtmhub-accountId": "5be26318e5274a0007f17f61",
},
"data": body
}; $.ajax(settings).done(function (response) { console.log(response); });
 NOTE: You must install the module requests.
In a terminal window do: pip install requests



import requests, json

headers = { "Authorization" : "Bearer {token}", "gtmhub-accountId" : "{accountId}", "Content-Type" : "application/json" };

url = "https://app.gtmhub.com/api/v1/customFields/{id}"

body = { "_id": "string value", "description": "string value", "filterable": false, "label": "string value", "name": "string value", "operationalType": "string value", "orderId": 2, "targetIds": [ "string value 1", "string value 2" ], "targetTypes": [ "string value 1", "string value 2" ], "tooltip": "string value", "type": "string value", "visualizationKind": "string value" };

requests.put(url, data=json.dumps(body), headers = headers)
{
    "_id": "string value",
    "accountId": "string value",
    "dateCreated": "string value",
    "description": "string value",
    "filterable": false,
    "isPrivate": false,
    "label": "string value",
    "lastModified": "string value",
    "name": "string value",
    "operationalType": "string value",
    "orderId": 2,
    "pluginVersionId": "string value",
    "targetIds": [
        "string value 1",
        "string value 2"
    ],
    "targetTypes": [
        "string value 1",
        "string value 2"
    ],
    "tooltip": "string value",
    "type": "string value",
    "visualizationKind": "string value"
}
🔗
delete
/customFields/{id}
Deletes the specified custom field. This will not delete the already persisted data stored in the fields of other entities.
Parameters
NameTypeDescription
gtmhub-accountId
*
stringSpecifies the ID of the gtmhub account.
expected in header, sample value:
5be26318e5274a0007f17f61
id
*
stringSpecifies the ID of the custom field.
expected in path, sample value:
5be26318e5274a0007f17f61
Expected response codes
204no content
401unauthorized

curl -X DELETE 'https://app.gtmhub.com/api/v1/customFields/{id}' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer {token}' \
-H 'gtmhub-accountId: 5be26318e5274a0007f17f61' \

var settings = { "url": "https://app.gtmhub.com/api/v1/customFields/{id}", "method": "DELETE", "timeout": 0, "headers": { "Content-Type": "application/json", "Accept": "application/json", "Authorization": "Bearer {token}",
"gtmhub-accountId": "5be26318e5274a0007f17f61",
}
}; $.ajax(settings).done(function (response) { console.log(response); });
 NOTE: You must install the module requests.
In a terminal window do: pip install requests



import requests, json

headers = { "Authorization" : "Bearer {token}", "gtmhub-accountId" : "{accountId}", "Content-Type" : "application/json" };

url = "https://app.gtmhub.com/api/v1/customFields/{id}"



requests.delete(url, headers = headers)