What is an import API?
Turn external records into clear, validated application data. A practical introduction to contracts, transformations, errors, and job lifecycles.
Read the guideData Import API
Give every record a clear destination.
Start with your destination schema, not a pile of files. Explore patterns for receiving structured records, preserving identifiers, catching invalid values, and reporting what changed.
JSONCSV
Start with a small, explicit contract
Define the fields your application accepts, their types, and what missing values mean. Keep external identifiers as strings when their exact representation matters. Separate source metadata from ownership and permissions: an imported field should never choose a tenant or grant access.
For a first catalog import, agree on a product identifier, display name, and status. Add other fields only when their intended use and correction rules are clear.
Make mapping and validation visible
Rename fields through a versioned mapping and validate the result against the destination requirements. Keep parsing errors, invalid records, and destination conflicts distinct. A preview should show the original value, the proposed value, and any rule that changed it.
Decide whether partially valid batches can proceed. A helpful report names the source record, affected field, and correction needed rather than simply saying the file failed.
Plan the write and the retry
Use stable source identity to distinguish inserts from updates. Document whether blank values clear a field or leave it unchanged. Keep a logical job separate from its processing attempts so a connection interruption does not automatically create another import.
Before committing real records, test a repeated request, an invalid identifier, an unexpected field, and a batch that is interrupted after partial progress.
Turn the idea into a test
Use a small, representative source and write down the expected result for one accepted record, one correction, and one repeated attempt. Keep the original values and the destination expectations visible throughout the review.
Use the format guides for source decisions and the local quickstart to see a simple mapping in action.
From Import Notes
A little reading. A better workflow.
Map it. Validate it. Understand it.
Separate transformations from validation, make every conversion explainable, and design useful errors around an explicit destination contract.
Read the guide
Retry without the uncertainty.
Separate logical jobs from processing attempts and make duplicate handling, partial outcomes, and uncertain commits understandable.
Read the guide