Data Uploader

The Data Uploader imports pets, adopters, fosters, volunteers, donors, and surrenders from .csv, .xls, or .xlsx files. Open Settings > Records & Data > Data Uploader.

Choose a record type before starting. The uploader builds its field list from that record type's current form configuration, normally the default template.

If you have no file to import, choose Add pets manually (or the button for the selected record type) to open the create form instead. Your forms already include PawPlacer's default fields, and any existing customization is kept. Customize fields opens that record type's form in Settings > Forms.

AI Data Mapping receives column headers and form definitions, never row values. See Data Import Privacy for details.

Three-Step Import

1. Upload

Select or drop a spreadsheet. Use one header row and one record per row. PawPlacer reads the columns and prepares a preview; it does not write records at this step.

2. Map

Review how spreadsheet columns map to PawPlacer fields.

• Exact matches are accepted automatically.
• Possible matches must be confirmed.
• The uploader automatically sends unmatched column headers and available form field labels for AI Data Mapping, even when optional AI features are off. Unmatched columns can receive suggested matches or complete drafts for new form fields. Every suggestion remains review-only until you confirm it.
• You can choose another source column or leave an optional field unmapped.
• Required fields must be mapped before continuing.

Use the All fields, Needs review, and Not in your file filters or search for a field. Open a mapping row to inspect its type and import behavior.

Indexed and Repeated Columns

Some exports split one list into numbered columns, such as intakeConditions[0] and intakeConditions[1]. When those columns contain a manageable set of option-like values, the uploader combines them into one source during preparation. The mapping screen shows the original column names together so you can see what will be merged.

If the combined source does not already match a form field, AI Data Mapping can suggest one Multi-select field. Opening Review suggestion shows the normal field editor with the distinct spreadsheet values already filled in as options. You can rename the field, change its section or type, edit the options, or cancel before anything is created. After you add the field, the combined source is mapped to it automatically, preserving multiple selections from the same record.

The uploader only combines explicit numbered groups that start at [0] and have at least two columns. If the values are long prose, contain formatting that cannot become one option, or produce too many options for a useful field, the columns stay separate for individual review. It also avoids combining an indexed group into an existing single-choice field, which prevents later values from being discarded.

3. Review and Upload

The review step separates:

• Rows ready to import
• Invalid rows that will be skipped
• Advisory rows that will be imported with normalized values
• Unresolved pet references

Download the error report for excluded rows, correct the source file if needed, or continue with the valid rows. Nothing is written until you confirm Upload; the confirmation says how many records will be imported. When the upload finishes, the result shows how many records were imported and how many rows were skipped, with a link to the list of that record type.

Rows that will be saved with a value your file doesn't supply are called out at the top of the review step, with their row numbers and the value they'll get. A pet whose Name cell is blank is still imported, named Unknown. If no column is mapped to a required field that has a default, the review step says every record will be saved with that default.

A pet whose species isn't one of your organization's supported animals is still imported with that species. The review step names the species and the rows that use it, so you can add it under Settings > Organization > Supported Animals if it should appear in species choices and filters.

A microchip number that isn't 9, 10, or 15 letters and digits, ignoring spaces and dashes, is still imported, and the review step lists the rows so you can check them.

A pet name longer than 255 characters is not imported as written: when Name has its import default (Unknown), the review step warns that the row will be saved with that name; otherwise the row is listed as invalid.

If an import stops partway, the dialog keeps track of what was already saved and shows each row's outcome. When your own records refused a batch, for example because several existing people share an imported email or a foster is already at capacity, the message says so. Download recovery report lists every row with its outcome, the reason it failed, and any pet links that were skipped, and Retry remaining work sends only the failed or unstarted work. Download the report before leaving, because the recovery progress is kept only while the import stays open.

Normalization

The importer handles common spreadsheet variations, including:

• Whitespace and empty placeholder cleanup
• Common yes/no formats
• Number fields that carry units or currency symbols, such as 45 lbs or $150. A cell holding more than one number, such as 12 lbs 4 oz, is read as empty rather than joined into one number.
• List values separated by commas, semicolons, or pipes
• Option-friendly lists split across bracketed columns such as field[0], field[1], and field[2]
• Species, sex, size, coat, health, and age-category variants
• Microchip values stored as strings so leading zeroes are retained
• Status labels mapped to the organization's current pet statuses
• Custom fields from the selected form template

The review screen shows important defaults and status-import choices before data is saved.

Optional fields the file leaves blank, or doesn't include at all, stay empty. PawPlacer doesn't guess a pet's species, sex, size, health, or age category. When one of those cells, or a foster's capacity, holds something the importer can't read, the review step lists it, that value is skipped, and the rest of the row is still imported.

Donor imports support the normal contact fields, donor status, notes, and configured custom fields. Surrender imports also support intake stage, priority, requested and scheduled intake dates, notes, and configured custom fields. When an imported foster has no capacity value, the foster has no capacity limit. A capacity of zero, or a number too large to store, is skipped instead of failing the import, so a new foster then has no capacity limit either.

Linking Pets

You can import fosters and adopters without linking them to pets. To link them, import pets first with stable custom_id values. Adopter and foster files can then include a pet_ids column containing PawPlacer pet UUIDs or custom IDs; separate multiple references with commas.

The review step identifies unresolved references. Valid references can create historical adoption links or foster assignments as part of the import. A foster link to a pet that is no longer in care (for example adopted, transferred, or archived) is skipped rather than stopping the import: the rest of the file is imported, and a warning afterwards says how many pet links were skipped.

Existing Records and Duplicates

For adopter, foster, volunteer, donor, and surrender files, PawPlacer compares trimmed email addresses without regard to capitalization:

• Rows in the same file with the same email are combined. The first nonempty scalar value is kept, while list values, pet references, and custom-field data are merged.
• If exactly one existing record of that type has the email, the import updates it instead of creating a duplicate.
• More than one existing match is treated as ambiguous: the import stops at that batch and says so. Merge those records, then retry.

Pet imports use custom_id as the stable update key. A matching existing pet is updated; repeating the same custom ID within one import stops the upload so the source can be corrected. Duplicate microchip values are cleared or reported with a warning rather than being assigned twice.

A matched record keeps the form it already uses, even when that is not the form the uploader mapped. Imported answers to questions its form asks are merged in, and answers to questions it does not ask are not saved. For people, the uploader reports after the import how many matched records this affected.

An update only changes what the file supplies. Values PawPlacer fills in for a missing or blank column — a field's default, a generated name, the intake status — are used for new records and never overwrite an existing record's value.

Pet image columns may contain existing image URLs. During upload, PawPlacer tries to fetch each image, convert it to WebP, and store it with the organization's media. If the browser and server hosting attempts both fail, the original source URL is kept instead, so keep the old host available until the imported profiles have been checked.

Help

Use the uploader's contact action when a spreadsheet needs migration help.

Permissions

Data Uploader requires Administrator access.