loading

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

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

Content type
application/json
{
  • "meta": {
    },
  • "response": {
    }
}

Custom Fields: Create

Creates a new Custom Field in an Account.

path Parameters
accountId
required
string
query Parameters
v
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.

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_LIST" "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 LOCATION_LIST type has been renamed to ENTITY_LIST. The former can still be obtained by calling Custom Fields endpoints with a v param before 20180809.

Responses

Request samples

Content type
application/json
{
  • "name": {
    },
  • "options": [
    ],
  • "group": "NONE",
  • "description": {
    },
  • "alternateLanguageBehavior": "PRIMARY_ONLY",
  • "validation": {
    },
  • "entityAvailability": [
    ],
  • "id": "string",
  • "type": "BOOLEAN"
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": {
    }
}

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
v
required
string

A date in YYYYMMDD format.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": {
    }
}

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
v
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

Content type
application/json
{
  • "name": {
    },
  • "options": [
    ],
  • "group": "NONE",
  • "description": {
    },
  • "alternateLanguageBehavior": "PRIMARY_ONLY",
  • "validation": {
    },
  • "entityAvailability": [
    ]
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": {
    }
}

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
v
required
string

A date in YYYYMMDD format.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": { }
}