Custom Fields | Hitchhikers Platform

Overview

The Custom Fields Endpoint Group allows you to retrieve, create, and update Custom Fields stored in the Knowledge Graph.

Each Custom Field is identified using its unique id and will return the details and configurations of the Custom Field.

Custom Fields are configured on the account level, so any adjustments made to Custom Fields will apply to all entities that leverage that Custom Field.

When updating a custom field you can adjust the configuration including: Name, Group, Description, Alternate Language Behavior, Field Specification, and Entity Availability.
- If these options are modified, this update will be reflected everywhere this Custom Field is being used.
Deleting custom fields will remove that Custom Field from all entities, and all content stored in those Custom Fields will be permanently deleted.

Use Cases

Create custom fields
Retrieve a list of all custom fields in your account, including their names, types and IDs

Guides

Create Custom Fields Unit

Custom Fields: List

Returns a list of Custom Fields in an Account.

path Parameters

accountId

required

string

query Parameters

v required	string A date in `YYYYMMDD` format.
offset	integer Default: 0 Number of results to skip. Used to page through results. Cannot be used together with `pageToken`.
limit	integer <= 1000 Default: 100 Number of results to return.
pageToken	string If a response to a previous request contained the `pageToken` field, pass that field's value as the `pageToken` parameter to retrieve the next page of data.

Responses

Response samples

200
default

Content type

application/json

{"meta": {"uuid": "4f72b877-e2d0-4de4-9324-b9cf2c03e1a0"
},
"response": {"count": 0,
"customFields": [{"name": {"value": "string",
"translations": [{"languageCode": "string",
"value": "string"
}
]
},
"options": [{"key": "string",
"value": "string",
"translations": [{"languageCode": "string",
"value": "string"
}
]
}
],
"group": "NONE",
"description": {"value": "string",
"translations": [{"languageCode": "string",
"value": "string"
}
]
},
"alternateLanguageBehavior": "PRIMARY_ONLY",
"validation": {"minCharLength": 0,
"maxCharLength": 0,
"minItemCount": 0,
"maxItemCount": 0,
"minValue": 0,
"maxValue": 0,
"minDate": "string",
"maxDate": "string",
"aspectRatio": "UNCONSTRAINED",
"minWidth": 0,
"minHeight": 0,
"entityTypes": ["location"
],
"richTextFormats": ["bold"
],
"entityRelationship": {"type": "ONE_WAY",
"relatedFieldId": "string",
"supportedDestinationEntityTypes": [ ]
}
},
"entityAvailability": ["location"
],
"id": "string",
"type": "BOOLEAN"
}
],
"pageToken": "string"
}
}

Custom Fields: Create

Creates new Custom Field(s) in an Account.

NOTE: If the v parameter is on or after 20220615, the request body must be an array, as to allow multiple field creates per request.

path Parameters

accountId

required

string

query Parameters

required

string

A date in YYYYMMDD format.

Request Body schema: application/json

Array

required	object The Custom Field's name (including default value and translations). After March 19th 2020, if users Update Custom Field's name using older versions of the API without explicitly specifiying translations, any existing translations will be cleared. Example: "name": { "value": "The promotions", "translations": [ { "languageCode": "fr", "value": "Les promotions" } ] }
	Array of objects Present if and only if `type` is `SINGLE_OPTION` or `MULTI_OPTION`. List of options (key, value, and translations) for the Custom Field. Example: { { "key": "TEMPORARILY_CLOSED", "value": "Temporarily Closed" }, { "key": "COMING_SOON", "value": "Coming Soon" }, { "key": "CLOSED", "value": "Closed" "translations": [ { "languageCode": "fr", "value": "Fermé" } ] }, { "key": "OPEN", "value": "Open" } } The behavior of the options' keys depends on which Custom Fields endpoint you are using: Get and List: The options' keys will be included in the response. Create: Do not specify option keys. They will be automatically assigned when the field is created. Update: If you include an option with an existing key, the option with that key will be updated with the value you specify. If you would like to add an option, specify its value but not its key, as the key will be automatically assigned when the option is added. NOTE: If you do not include an existing option in your Update request, it will be deleted.
group	string Default: "NONE" Enum: "NONE" "GROUP_1" "GROUP_2" "GROUP_3" "GROUP_4" "GROUP_5" "GROUP_6" "GROUP_7" "GROUP_8" "GROUP_9" "GROUP_10" "GROUP_11" "GROUP_12" "GROUP_13" "GROUP_14" "GROUP_15" "GROUP_16" "GROUP_17" "GROUP_18" "GROUP_19" "GROUP_20" "GROUP_21" "GROUP_22" "GROUP_23" "GROUP_24" "GROUP_25" "GROUP_26" "GROUP_27" "GROUP_28" "GROUP_29" "GROUP_30" The Custom Field's group.
	object The Custom Field's description (including value and translations) which, if provided, will be shown as a tooltip next to the Custom Field in the Knowledge Manager. Providing a description is highly recommended when creating apps for the App Directory. After March 19th 2020, if users Update Custom Field's description using older versions of the API without explicitly specifiying translations, any existing translations will be cleared. Example: "description": { "value": "This is the list of promotions", "translations": [ { "languageCode": "fr", "value": "Ceci est la liste des promotions" } ] }
alternateLanguageBehavior	string Default: "PRIMARY_ONLY" Custom Field multi-language profile behavior, which is one of: `PRIMARY_ONLY`: The Custom Field can only have a value set on its primary language profile. `OVERRIDABLE`: The Custom Field can have a value set on any alternate language profiles, which will override the primary language profile value when the alternate language profile is requested. When requested, if a value is not set for an alternate language profile, the primary language profile value will be returned. `LANGUAGE_SPECIFIC`: The Custom Field can have a value set on any alternate language profiles. When requested, if a value is not set for an alternate language profile, no value will be returned.
	object A Custom Field validation object, describing validation rules when a Custom Field value is set or updated.
entityAvailability	Array of strings Items Enum: "location" "event" "healthcareProfessional" "healthcareFacility" "atm" "restaurant" A list of entity types that the Custom Field is available to.
id	string ID that should be used when referencing the field in API calls. This ID will also serve as the Custom Field's key in our upcoming Entities API endpoints. Note that in Locations endpoints, Custom Fields are still referenced by their numeric `id`, which can be obtained by calling the Custom Fields: List endpoint with a `v` param before `20180809`. (For Create requests) Must have a prefix of `c_` and contain only alphanumeric characters or underscores.
type required	string Enum: "BOOLEAN" "CTA" "DAILY_TIMES" "DATE" "GALLERY" "HOURS" "ENTITY_RELATIONSHIP" "MULTILINE_TEXT" "MULTI_OPTION" "NUMBER" "PHOTO" "RICH_TEXT" "SINGLE_OPTION" "TEXT" "TEXT_LIST" "URL" "VIDEO" "VIDEO_GALLERY" The data type of the Custom Field's contents. Note that the `ENTITY_LIST` type has been renamed to `ENTITY_RELATIONSHIP`. The former can still be obtained by calling Custom Fields endpoints with a `v` param before `20220615`. Before `20180809`, this type was named `LOCATION_LIST`.

Responses

Request samples

Payload

Content type

application/json

[{"name": {"value": "string",
"translations": [{"languageCode": "string",
"value": "string"
}
]
},
"options": [{"key": "string",
"value": "string",
"translations": [{"languageCode": "string",
"value": "string"
}
]
}
],
"group": "NONE",
"description": {"value": "string",
"translations": [{"languageCode": "string",
"value": "string"
}
]
},
"alternateLanguageBehavior": "PRIMARY_ONLY",
"validation": {"minCharLength": 0,
"maxCharLength": 0,
"minItemCount": 0,
"maxItemCount": 0,
"minValue": 0,
"maxValue": 0,
"minDate": "string",
"maxDate": "string",
"aspectRatio": "UNCONSTRAINED",
"minWidth": 0,
"minHeight": 0,
"entityTypes": ["location"
],
"richTextFormats": ["bold"
],
"entityRelationship": {"type": "ONE_WAY",
"relatedFieldId": "string",
"supportedDestinationEntityTypes": [ ]
}
},
"entityAvailability": ["location"
],
"id": "string",
"type": "BOOLEAN"
}
]

Response samples

201
default

Content type

application/json

{"meta": {"uuid": "4f72b877-e2d0-4de4-9324-b9cf2c03e1a0"
},
"response": [{"id": "string"
}
]
}

Custom Fields: Get

Gets a specific Custom Field in an Account.

path Parameters

accountId required	string
customFieldId required	string ID that should be used when referencing the field in API calls. This ID will also serve as the Custom Field's key in our upcoming Entities API endpoints. Note that the Custom Fields can still be accessed using their numeric `id` by invoking the endpoints with a `v` param before `20180809`.

query Parameters

required

string

A date in YYYYMMDD format.

Responses

Response samples

200
default

Content type

application/json

{"meta": {"uuid": "4f72b877-e2d0-4de4-9324-b9cf2c03e1a0"
},
"response": {"name": {"value": "string",
"translations": [{"languageCode": "string",
"value": "string"
}
]
},
"options": [{"key": "string",
"value": "string",
"translations": [{"languageCode": "string",
"value": "string"
}
]
}
],
"group": "NONE",
"description": {"value": "string",
"translations": [{"languageCode": "string",
"value": "string"
}
]
},
"alternateLanguageBehavior": "PRIMARY_ONLY",
"validation": {"minCharLength": 0,
"maxCharLength": 0,
"minItemCount": 0,
"maxItemCount": 0,
"minValue": 0,
"maxValue": 0,
"minDate": "string",
"maxDate": "string",
"aspectRatio": "UNCONSTRAINED",
"minWidth": 0,
"minHeight": 0,
"entityTypes": ["location"
],
"richTextFormats": ["bold"
],
"entityRelationship": {"type": "ONE_WAY",
"relatedFieldId": "string",
"supportedDestinationEntityTypes": [ ]
}
},
"entityAvailability": ["location"
],
"id": "string",
"type": "BOOLEAN"
}
}

Custom Fields: Update

Updates a single Custom Field in an Account.

Note that the only updatable values in an existing Custom Field are its name, group, description, alternate language behavior, as well as available options if its type is SINGLE_OPTION or MULTI_OPTION.

If options are modified, every location with that option selected will have the new value.
If options are deleted, all locations with that option will no longer have that option selected.
If the deleted options are the only options selected for a location, the location will no longer have a value set for that Custom Field.

path Parameters

accountId required	string
customFieldId required	string ID that should be used when referencing the field in API calls. This ID will also serve as the Custom Field's key in our upcoming Entities API endpoints. Note that the Custom Fields can still be accessed using their numeric `id` by invoking the endpoints with a `v` param before `20180809`.

query Parameters

required

string

A date in YYYYMMDD format.

Request Body schema: application/json

required	object The Custom Field's name (including default value and translations). After March 19th 2020, if users Update Custom Field's name using older versions of the API without explicitly specifiying translations, any existing translations will be cleared. Example: "name": { "value": "The promotions", "translations": [ { "languageCode": "fr", "value": "Les promotions" } ] }
	Array of objects Present if and only if `type` is `SINGLE_OPTION` or `MULTI_OPTION`. List of options (key, value, and translations) for the Custom Field. Example: { { "key": "TEMPORARILY_CLOSED", "value": "Temporarily Closed" }, { "key": "COMING_SOON", "value": "Coming Soon" }, { "key": "CLOSED", "value": "Closed" "translations": [ { "languageCode": "fr", "value": "Fermé" } ] }, { "key": "OPEN", "value": "Open" } } The behavior of the options' keys depends on which Custom Fields endpoint you are using: Get and List: The options' keys will be included in the response. Create: Do not specify option keys. They will be automatically assigned when the field is created. Update: If you include an option with an existing key, the option with that key will be updated with the value you specify. If you would like to add an option, specify its value but not its key, as the key will be automatically assigned when the option is added. NOTE: If you do not include an existing option in your Update request, it will be deleted.
group	string Default: "NONE" Enum: "NONE" "GROUP_1" "GROUP_2" "GROUP_3" "GROUP_4" "GROUP_5" "GROUP_6" "GROUP_7" "GROUP_8" "GROUP_9" "GROUP_10" "GROUP_11" "GROUP_12" "GROUP_13" "GROUP_14" "GROUP_15" "GROUP_16" "GROUP_17" "GROUP_18" "GROUP_19" "GROUP_20" "GROUP_21" "GROUP_22" "GROUP_23" "GROUP_24" "GROUP_25" "GROUP_26" "GROUP_27" "GROUP_28" "GROUP_29" "GROUP_30" The Custom Field's group.
	object The Custom Field's description (including value and translations) which, if provided, will be shown as a tooltip next to the Custom Field in the Knowledge Manager. Providing a description is highly recommended when creating apps for the App Directory. After March 19th 2020, if users Update Custom Field's description using older versions of the API without explicitly specifiying translations, any existing translations will be cleared. Example: "description": { "value": "This is the list of promotions", "translations": [ { "languageCode": "fr", "value": "Ceci est la liste des promotions" } ] }
alternateLanguageBehavior	string Default: "PRIMARY_ONLY" Custom Field multi-language profile behavior, which is one of: `PRIMARY_ONLY`: The Custom Field can only have a value set on its primary language profile. `OVERRIDABLE`: The Custom Field can have a value set on any alternate language profiles, which will override the primary language profile value when the alternate language profile is requested. When requested, if a value is not set for an alternate language profile, the primary language profile value will be returned. `LANGUAGE_SPECIFIC`: The Custom Field can have a value set on any alternate language profiles. When requested, if a value is not set for an alternate language profile, no value will be returned.
	object A Custom Field validation object, describing validation rules when a Custom Field value is set or updated.
entityAvailability	Array of strings Items Enum: "location" "event" "healthcareProfessional" "healthcareFacility" "atm" "restaurant" A list of entity types that the Custom Field is available to.

Responses

Request samples

Payload

Content type

application/json

{"name": {"value": "string",
"translations": [{"languageCode": "string",
"value": "string"
}
]
},
"options": [{"key": "string",
"value": "string",
"translations": [{"languageCode": "string",
"value": "string"
}
]
}
],
"group": "NONE",
"description": {"value": "string",
"translations": [{"languageCode": "string",
"value": "string"
}
]
},
"alternateLanguageBehavior": "PRIMARY_ONLY",
"validation": {"minCharLength": 0,
"maxCharLength": 0,
"minItemCount": 0,
"maxItemCount": 0,
"minValue": 0,
"maxValue": 0,
"minDate": "string",
"maxDate": "string",
"aspectRatio": "UNCONSTRAINED",
"minWidth": 0,
"minHeight": 0,
"entityTypes": ["location"
],
"richTextFormats": ["bold"
],
"entityRelationship": {"type": "ONE_WAY",
"relatedFieldId": "string",
"supportedDestinationEntityTypes": [ ]
}
},
"entityAvailability": ["location"
]
}

Response samples

200
default

Content type

application/json

{"meta": {"uuid": "4f72b877-e2d0-4de4-9324-b9cf2c03e1a0"
},
"response": {"id": "string"
}
}

Custom Fields: Delete

Deletes a Custom Field in an Account.

The Custom Field will be removed from all locations, and all content entered in the Custom Field will be deleted permanently.

path Parameters

accountId required	string
customFieldId required	string ID that should be used when referencing the field in API calls. This ID will also serve as the Custom Field's key in our upcoming Entities API endpoints. Note that the Custom Fields can still be accessed using their numeric `id` by invoking the endpoints with a `v` param before `20180809`.

query Parameters

required

string

A date in YYYYMMDD format.

Responses

Response samples

200
default

Content type

application/json

{"meta": {"uuid": "4f72b877-e2d0-4de4-9324-b9cf2c03e1a0"
},
"response": { }
}