Map Fields

Select Entity Type

Select the entity type to map your data to. Only fields enabled on the selected entity type will be available for mapping. This can be changed at any time.

Mapping to multiple entity types

 If multiple entity types are selected, include a column with the entity type's API name (e.g., blogPost) and map it to "Entity Type." Note that this cannot be used to change the type of an existing entity.

If a field is enabled on only a subset of selected entity types, it is still an eligible mapping — but values provided for entity types that don't support the field will be silently ignored.

Map Column Headers

When an entity type is selected, the connector will attempt to auto-map column headers to matching fields. You can change any auto-mapped field. Mapping all columns is not required. Unmapped columns are ignored.

Sample Data

This column is populated using the first non-null value for that column header, as shown in the preview table data. This means that the sample data may not all be data for the same row (entity).

If all preview table data is null for a given column header, then the Sample Data column will be blank.

Blank Value Behavior

When mapping a column to a field, designate the behavior for blank values. The default option is to Clear Value if Blank = False, or you can choose to Clear Value if Blank = True.

This configuration is set at the field level, meaning that different behavior can be designated for different fields on a single entity.

For the table below, use an example entity with Entity ID 123 and the Date field populated to 2023-01-01.

Special Field and Field Type Behavior

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 ID

To change the entity ID of an existing entity, you can map a column header to “Entity ID (Updated Value)” in addition to mapping the current ID of that entity to “Entity ID”. If both mappings are provided and the value for “Entity ID (Updated Value)” is not blank, then the existing entity (matched on the value provided in the “Entity ID” column) will be updated to reflect the newly provided entity ID.

Entity Relationship

Values must be valid, existing Entity IDs.

• If the referenced Entity ID does not exist: the field update is ignored, but other updates to the same entity still process. Logged as a warning in etl_diagnostics.csv.
• If the referenced Entity ID exists but is an invalid reference type (e.g., referencing a Restaurant entity where only Product entities are valid): the entire entity update fails. Logged as an error in entity_diagnostics.csv.

Hours and Holiday Hours

See the Hours Field Mapping below.

List

See the List Field Mapping below. 

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

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. 

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:

• Map to Country Code or Address > Country Code (or both, but in this case, Address and Country Code values must match).
• If neither is provided, the country defaults to the Yext account's country.

For existing entities, the Country Code mapping is not required, but if provided it must match the entity's existing Country Code. Country Code cannot be changed after an entity is created.

Folders

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.

Labels

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.

Unsupported Field Types

The following field types cannot be mapped to in a connector:

• Linked Accounts
• ECLs

Hours Field Mapping

The Hours and Holiday Hours fields accept data in several formats. Choose the format that matches how your source data is structured.

Hours Field

Time Format

A single column per day of the week contains the full set of hours for that day, or marks the business as closed.

API Format

Separate columns for start time, end time, and isClosed for each interval and day. Repeat these columns for each day of the week.

Example for Monday:

Holiday Hours Field

Note: For more on how publishers handle holiday hours on listings, see the Holiday Hours on Publishers reference.

Combined Date and Time

Date and time intervals are in a single column. Multiple dates can be combined in one column or given their own columns. If a single column contains multiple dates with multiple intervals each, separate each day using a non-comma delimiter (e.g., |).

Multiple dates in one column:

Each date in its own column:

Separated Date and Time

Dates and times are in separate columns. A single column may contain multiple dates or multiple intervals, but not both in the same column. Use a non-comma delimiter (e.g., |) to separate days within a column when a day has multiple intervals.

Each date in its own column:

Multiple dates in one column:

Separated API Format

Separate columns for date, start time, end time, isClosed, and isRegularHours. Multiple intervals per date can be in separate columns or combined in one.

Single date and interval per column:

Multiple dates in one column (set ClearIfBlank = TRUE for all columns):

Accepted Date and Time Formats

Dates: Use YYYY-MM-DD format (e.g., 2024-12-22).

Times: Periods can substitute for colons (13:00 = 13.00). Spaces are ignored. Not case-sensitive.

List Field Mapping

List-type fields have two configuration decisions: whether to overwrite or append existing items, and whether to map data as an entire list or individual items.

Overwrite vs. Append

If any item in the list is invalid, the entire entity update will fail.

Note: Categories and Google Attributes always use overwrite behavior and must always be provided as an entire list.

Entire List vs. Individual Items

Entire list: Provide all list items in a single column, separated by a delimiter.

Individual items: Provide each item in its own indexed column (e.g., Education [0], Education [1]). Commas within a value are treated as part of the value, not as separators. Even when appending, the first index should be 0.

Example of individual items:

The field mappings would appear as follows in Yext:

From these mappings, entities would be created with two Education list objects. For example, the Education list object on Entity ID 1 would appear as below:

Validation

Connector validation follows the same rules as the Entities API. If a value would fail validation when entered via Entity Edit, it will likely fail in a connector run as well. This can be a useful way to manually debug failing entities.