Visit data manual upload guide

File Requirements

Before uploading, prepare your file using the correct format. You can download a template directly from the platform. Two formats are available: Excel and CSV. Both contain the same fields, the file format is the only difference.

General Requirements:

• The file must contain a header row with the header names exactly as specified in the template.
• Maximum file size: 5 MB.
• Accepted formats:
  • .xls (Excel 97-2003)
  • .xlsx (Excel 2007 and later)
  • .csv (using comma , or semicolon ; as separator)
  • .txt (using comma , or semicolon ; as separator)
• The maximum number of records per file depends on which upload you use: 500 for entity-level uploads, 1,000 for organization-level uploads. See each section below for details.

🔎 Tip: The template includes 2 rows of example data, make sure to delete or overwrite them before uploading.

Both templates share the same rules for date and language columns:

• Arrival Date / arrival_date (optional): Format must be YYYY-MM-DD. If left empty, the platform automatically uses the current UTC date and time.
• Departure Date / departure_date (optional): Format must be YYYY-MM-DD. If left empty, the platform automatically uses the current UTC date and time.
• Language / guest_language (optional): Defaults to en (English) if empty. Provide the language as detailed in the Supported language codes list.

🔎 Note on Timestamps: You can optionally include a timestamp (HH:MM:SS) in the Arrival Date or Departure Date columns. The timestamp must follow the UTC timezone.

How timestamps affect email sending:

• If no timestamp is added: the email may be sent anytime after 00:00:00 UTC on the specified date.
• If a timestamp is included: the email may be sent anytime after the specified UTC timestamp on that date.

💡 This gives you additional control over email scheduling and Survey delivery time.

Entity-Level Upload (One Entity, One Survey at a Time)

Use this option to upload guest data for one Entity and one Survey at a time.

Where to Find It

1. Navigate to the manual upload page in CXP for the Entity you want to upload data for.
2. Click on the Entity and select the opcion "Visit data uploads"
3. Select the Survey the guest data should be assigned to. This is the Survey that will be sent to the guests.
   • You can search for a Survey by name.
   • If you don't see the Survey, it might be because it has no questionnaires inside, or email distribution is not configured. Check your Survey settings in the Survey Manager.

Template Columns

• Email (mandatory): Must be in a valid email format (e.g., guest@example.com).
• First Name (optional): Can be left empty or contain any text.
• Last Name (optional): Can be left empty or contain any text.
• Arrival Date (optional): see File Requirements above.
• Departure Date (optional): see File Requirements above.
• Language (optional): see File Requirements above.

Maximum of 500 records per file.

Uploading the File

Once your file is prepared, click Upload File, choose your file, and confirm.

• ⚠️ There is no way to cancel or undo an upload once it starts.
• After upload, the assigned Survey will be ready to send to the guests.

Check the Results

After the upload is completed, results appear in the Last Uploads section at the bottom of the page. You'll see:

• File name: Name of the uploaded file.
• Survey: Survey selected when uploading the file.
• Total Records: Number of rows in the uploaded file.
• Unique Records: Count of unique email addresses.
• Valid Records: Records successfully processed.
• Invalid Records: Records rejected due to errors.

Organization-Level Upload (Multiple Entities and Surveys)

If your organization manages multiple properties, you don't need to upload guest data one Entity at a time. This option lets you upload a single file that covers several Entities and Surveys at once.

🔎 Note: Organization-level upload is available to admin and editor users with access to all Entities in the organization. It's only available on the Enterprise (ENT) subscription.

Where to Find It

1. Go to the Entities section.
2. Select the tab Visit data uplaods 
3. In this tab, you'll find the same options as the entity-level upload: Upload Visit Data and the Last Uploads section.

From here, you can download the template, upload your file, and click the upload guide link to come back to this article for help.

Template Columns

The organization-level template adds two columns to the front of the file, to identify which Entity and Survey each guest record belongs to. Column order matters:

1. entity_id (mandatory): The Entity the guest record belongs to.
2. survey_id (mandatory): The Survey the guest should receive.
3. guest_email (mandatory): Must be in a valid email format.
4. guest_first_name (optional)
5. guest_last_name (optional)
6. arrival_date (optional): see File Requirements above.
7. departure_date (optional): see File Requirements above.
8. guest_language (optional): see File Requirements above.

Maximum of 1,000 records per file. This is higher than the 500-row limit for entity-level uploads, since one file now covers multiple Entities and Surveys.

🔎 Note: The entity-level upload and the organization-level upload use different templates, and each rejects the other's file. If your file has entity_id and survey_id columns, only the organization-level upload accepts it. If it doesn't have these columns, only the entity-level upload accepts it.

Uploading the File

Once your file is ready, upload it the same way as for a single Entity: choose your file and confirm.

• ⚠️ There is no way to cancel or undo an upload once it starts.

Check the Results

After the upload is completed, results appear in the Last Uploads section in the new tab. You'll see:

• File name: Name of the uploaded file.
• Surveys: Count of different Surveys included in the file.
• Entities: Count of different Entities included in the file.
• Total Records: Total rows in the file.
• Unique Records: Unique rows in the file. For organization-level uploads, a unique record is the combination of an email address and a Survey ID, since the same guest can appear across different Surveys.
• Valid Records: Records with valid data that were processed.
• Invalid Records: Records that failed validation.
• Upload date: Date of the upload.
• Download: Button to download the processed report.

In addition to the validation errors described in Fixing Invalid Records below, three new errors can appear for organization-level uploads:

• Entity id does not exist in the organization.
• Survey id does not exist in the organization.
• Survey id is not eligible for manual upload. This happens when the manual upload setting is off, or when no questionnaire in the Survey includes an Entity in its scope.

The downloaded report includes your original file, with the entity_id and survey_id columns, plus the status and details for each record.

How Email Distribution Works

If the Departure Date is more than 30 days before the upload date:

• The visit is considered expired.
• No email is sent.
• The visit appears in the visit status list with the status Not processed.
• The visit appears in the visit volume list under the status Not processed.

If the departure date is within the next 30 days (starting tomorrow or later relative to the upload date):

• The email is not sent immediately.
• The visit appears in the visit status list with the status Ready to send.
• The visit appears in the visit volume list under the status Ready to send.
• The email is automatically sent on the departure date or within the following hours.

If the departure date is more than 30 days in the future:

• The visit is considered expired.
• No email is sent.
• The visit appears in the visit status list with the status Not processed.
• The visit appears in the visit volume list under the status Not processed.

This logic ensures that Surveys are sent at the right time and prevents outdated or excessively early communication. It works the same way whether you use entity-level or organization-level upload.

Fixing Invalid Records

This process works the same way for both entity-level and organization-level uploads: the whole file is processed record by record. Valid records are processed and invalid records are reported. Processing does not stop when an error is found.

If your upload returns a "Contains errors" status:

1. Download the file from the Last Uploads table.
2. Remove all rows marked as Success.
3. Fix the rows marked with errors, the Details column explains the issue.
4. Delete the Status and Details columns (including headers).
5. Save the corrected file and upload it again using the same process.

Additional Information

• Upload history is retained for 60 days. Records older than that are automatically removed.
• Always double-check your data before uploading, as there's no undo option.
• Distribution status tracking still happens at the Entity level. To check the status of Surveys uploaded through the organization-level upload, go to the specific Entity.