The Entity Upload Tool allows you to update and add entities to your account in bulk by uploading a spreadsheet. This article outlines the process of uploading your spreadsheet, as well as some best practices to be aware of, and additional information on some of the error messages you may encounter when uploading your data file.

For steps to upload this information, see Add and edit entities through spreadsheet upload. For details on each field that can be included in the upload, see Entity Upload Template Details.

Uploading Entity Information (preparing your spreadsheet file)

• Configuring your upload template:
  
  • If you already have entities in the Yext platform, we recommend exporting your entities and updating that file to both add new entities or update existing entities.
  • Make sure that the first tab of the Excel file includes the entity information you would like to upload to the platform, as the Upload Tool can only read the first tab of the Excel File.
  • You can upload a variety of entity types in the same file, you just need to make sure you specify the ‘Entity Type’ for each entity and that you include the correct fields for each entity type.
• Entity ID or Yext ID:
  • The file must contain an identifier column (e.g., Entity ID or Yext ID). To easily obtain the Entity ID or Yext ID, export your entity information. These two fields are included in every export by default.
    • When updating existing entities, you can include either the Entity ID or the Yext ID.
    • When adding a new entity, you will need to include an Entity ID. Yext ID will be created automatically once the entity is uploaded.
    • When adding events, if the event is associated with a location already stored in Yext, you will need to add an Entity ID for the event, as well as the Entity ID for the associated location.
• Address:
  • When uploading address information you must include all required address fields. Required address fields are country specific (and should be marked as Required in the upload template). For entities in the U.S. this includes all of the following fields:
    • Address > Line 1
    • Address > City
    • Address > Region
    • Address > Post Code
    • Country Region
• Number fields (e.g., Yext ID, Store ID, Phone Number):
  • Make sure that all IDs are converted to a number in the spreadsheet file. Fields such as Store ID or Country Code may get rejected if it is being read as a text string or anything that is not a number.
• Hours:
  • If you are uploading hours you must include the hours for all seven days of the week, you cannot just include one day. Note, this is not the case if you are adding holiday hours.
  • Business Hours can be separated into columns for their open and close times. If you use this method in your file the proper Yext Field Names are “Hours > Monday > Start”, “Hours > Monday > End”, etc.

 

Mapping Entity Information (configuring the upload in the Yext platform)

• All required fields must be mapped and included for new entities. See Add Entities: Required Content & Upload Forms for a list of required fields.
• The Featured Message is a Required Field for your entities, but the Featured Message URL is optional. 
• If there are any columns you’d like to omit from the upload do not map that field and choose Ignore All Unmapped Columns in the Yext Platform once you’ve completed mapping for all the others.
• Replace Existing vs Add to Existing
  • One thing to note is that certain multi-select fields or fields with multiple sub-fields will default to replace the content in the platform with the content in the file.
    
    • These fields include:
      • Multi-select fields
        • Google Business Profile attributes
        • Payment Methods
        • Healthcare-specific fields (Admitting Hospitals, Conditions Treated, Degrees, etc.)
      • Fields with sub-fields
        • Photo Gallery fields
        • Emails
        • Labels
        • Search Tracker Fields
        • Enhanced Content List Fields
        • Additional Attributes
  • To add to the existing content, instead of overriding it click on the Edit button on the right side of the desired row, then select the checkbox next to Add to Existing. This will add the content to the list instead of replacing the content in the file with what already exists in the platform.
• You can add additional data that was not included in your original upload file. To do this, click Add Field in the Additional Fields section, and fill out the required information.

 

• Below you can find additional information on the field mapping for each field, as well as the fields that are required when adding new entities.

 

Fixing Errors

• There are two different ways to fix errors, which differ slightly depending on which field the error is in.
  • Fix Errors in Field View will only display for address-related errors. This will return a Knowledge Graph-like view where you can fix all errors by adding or editing values in the Address field for each entity.
  • Fix Errors in Spreadsheet View will display all non-address related errors. This will return the list of issues for you to review and correct. The data in your file is listed under the Data in File column, an explanation of the error can be found in the Error column, and you will enter in the correct information in the New Value column.
• You also have the option to download the errors and correct them in your entity file. Once you’ve corrected the errors in the downloaded file, you can restart the upload process with the newly revised file. To do this, click on the More Actions button and select Upload Revised File, click Choose File and select the desired file, then click Upload Revised File.

 

Understanding Specific Error Messages

• Address Fields:
  • An address error will appear even if it’s only an issue for one field. For example, the instance below has an unspecified region (state) that needs to be changed to “NY”. Make sure you add or edit the values for all of the other entities in the left sidebar before you click Continue.
  • Error messages:
    • “Value must be a postal code”
    • “Value is not a valid region.”
  • Resolution: You must include and map all address fields.
• Hours Fields:
  • Error message:
    • “The hours specified failed validation: Hours for all days must be specified”
  • Resolution: Hours must be entered for all days of the week.
  • Error message:
    • “The hours specified failed validation: Time interval must contain exactly one hyphen.”
  • Resolution: Hours must be entered as a time interval with a hyphen
    • Example: 09:00AM-05:00PM

Reviewing Changes: Glossary of Entity Groups

Once you have successfully uploaded the content into the platform, you will need to review and confirm the changes you have made. Once you acknowledge all of these changes, you will click Submit Changes to complete the upload process. See details on each group you must review:

• New Entities:
  • Entities that did not exist in the Knowledge Graph before and will be uploaded.
• Updated Entities:
  • Entities in the Knowledge Graph that were included in the file with one or several updates to its information.
• Unchanged Entities:
  • Entities in the Knowledge Graph that were included in the file but had no updates to its information.
• Missing Entities:
  • Entities in the Knowledge Graph that weren’t included in the file upload and therefore unchanged.