Special Field and Field Type Behavior | Yext Hitchhikers Platform

Certain fields and field types that expect a certain input format in order to correctly map to field values. This behavior is outlined below.

Field Type Behaviors

Entity Relationship

Mapping to an Entity Relationship field requires the value to be that of an existing, valid Entity ID.

If the referenced Entity ID does not exist in your account, the field update will be ignored, but any other updates to the same entity will still be processed This will be displayed as a warning diagnostic in the etl_diagnostics.csv file.

If the referenced Entity ID matches an entity that is not a valid reference (i.e., the Enitty ID is that of a Restaurant entity type, but only Product Entity Types are valid on the field), the entire entity update will fail. This will be displayed as an error in the entity_diagnostics.csv file.

Hours and Holiday Hours

See the Hours Field Mapping reference.


See the List Field Mapping reference.

Option (Multi- or Single-Option Select)

You must always use the External ID when ingesting data via the connector. Using a display name will result in an invalid type option. To find out the External ID of your options, navigate to Field Settings and view the name in parentheses under Validation > Available Options.

Rich Text v1 (Legacy Rich Text)

Rich Text (v1) fields can only accept data formatted as HTML. Rich Text (v1) fields are also not supported with the Apply Template Fields transform , nor are they supported as a field to extract in Advanced Comprehensive Mode.

All of the above is supported for Rich Text (v2) fields. If you have Rich Text (v1) fields that you would like to use for any of the above use cases, learn more about migrating your Rich Text (v1) fields to Rich Text (v2) in this guide: Migrate Legacy Rich Text Fields and Field Types

Yes/No (Boolean)

You must use values of the following format:

  • TRUE or true
  • FALSE or false


Categories can be mapped to either the Base Category List (e.g., Yext) or to a publisher as overrides. In order to successfully map your Categories, you must provide the correct API/ID as stored in our system.

  • To map to Yext categories, you must provide the numerical Yext ID.
  • To map to a publisher’s categories, you must provide their API name (e.g., for Google Business Profile, you must use the GBP ID, such as gcid:accountant. See the Google Business Profile reference for a list of Google categories).

To transform ingested Publisher IDs to correct Yext IDs in order to map to the Base (Yext) list, use the Map Publisher Categories Transform .

For more information on Category behavior in Connectors, see the Categories reference .

Country Codes

When creating a new entity, the Country Code can be set by mapping to either Country Code or Address > Country Code.

  • If both Address and Country Code are provided, the values must match.
  • If neither are provided, the country code of the new entity will default to the country of the Yext account.

If the Country Code field is mapped on an entity that already exists:

  • The Country Code mapping is not required.
  • The value(s) for Country Code and/or Address > Country Code must match the value for Country Code that is already on the entity already. This means the Country Code cannot be updated once the entity is created.


In order to map to folders, you can use the folder’s display name. There are two ways to map to a specific folder:

  • Folder Name (e.g., TestFolder1)
  • Folder Path (e.g., Parent Folder > Folder1 > TestFolder1)

If there are multiple subfolders in your account with the same name, you must use the Folder Path option. Otherwise, the update will fail as our system will not know which subfolder to map to.

You cannot currently create a new folder via the connector flow. You must map to a folder that already exists in the account.


Map to new or existing labels using a label display name. Just as with List fields, the entire list of labels provided in the mapping will be assumed to be comprehensive, and will overwrite any existing labels on the entity.

If an item in the list does not match that of the display name of an existing label, a new label will be added to the account and applied to the entities with that label.

If an item in the list matches the display name of an existing label, that existing label will be applied.