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.
- Create custom fields
- Retrieve a list of all custom fields in your account, including their names, types and IDs
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 |
offset | integer Default: 0 Number of results to skip. Used to page through results.
Cannot be used together with |
limit | integer <= 1000 Default: 100 Number of results to return. |
pageToken | string If a response to a previous request contained the |
Responses
Response samples
- 200
- default
{- "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
v required | string A date in |
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 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:
| |
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:
|
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 |
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 |
Responses
Request samples
- Payload
[- {
- "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
{- "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 |
query Parameters
v required | string A date in |
Responses
Response samples
- 200
- default
{- "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 |
query Parameters
v required | string A date in |
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 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:
| |
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:
|
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
{- "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
{- "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 |
query Parameters
v required | string A date in |
Responses
Response samples
- 200
- default
{- "meta": {
- "uuid": "4f72b877-e2d0-4de4-9324-b9cf2c03e1a0"
}, - "response": { }
}