Paperbox datasources let you load structured reference data (typically CSV) that Paperbox can use in workflows (e.g., matching, enrichment, routing, validations).
All datasource endpoints are part of the Integration API hosted at https://integration.{ENV}.paperbox.ai (with {ENV} = acc or prd).
Authentication uses a signed JWT plus an API key provided by Paperbox.
The 3 datasource routes (what they do)
1) Upload a full data version (replace everything)
Use this when you want to re-upload the entire datasource as a fresh, complete snapshot.
When to use
Initial load
Regular “full refresh” integrations (nightly/weekly full export)
Big corrections where replacing everything is simplest
2) Upsert data (insert or update rows)
Use this when you want to incrementally add new rows and update existing rows without re-sending the entire dataset.
When to use
Near-real-time updates (new/changed entities)
Daily delta exports
Keeping a datasource in sync without full reloads
Note: “Upsert” behavior relies on the datasource’s configured unique key(s) in Paperbox. If you’re unsure which key is configured, check the datasource settings in the UI.
Important: missing columns will result in a 400 Bard Request error, every upsert needs all columns.
3) Upload deletes (remove rows)
Use this when you want to delete entries from an existing datasource.
When to use
Entities removed in the source system
GDPR/retention removals (when applicable)
Cleaning up stale reference data
CSV payload expectations
All three routes accept:
content_type = text/csvpayloadas a binary file upload (your CSV content)
Practical tips:
Keep a header row with column names.
Ensure the key column(s) (unique identifier) are present and consistently formatted.
Prefer stable encodings (UTF-8) and consistent separators.
Uploading datasources manually via the UI
In addition to the Integration API, datasources can also be uploaded manually through the Paperbox UI.
When uploading via the UI:
Only JSON files are supported.
The JSON structure must match the datasource schema.
Important: Missing columns will result in a 400 Bad Request Error.
Just like with API uploads, new fields will automatically be created if they appear in the uploaded dataset.
Field types and configuration can still be adjusted afterward in the frontend (UI) if needed.
Manual uploads are typically useful for:
Quick fixes or testing
Small datasets
One-off updates
For automated or recurring updates, we recommend using the Integration API routes described above.
FAQ: “I need to add 1–2 new fields (columns). Can I just re-upload? Will the fields be created automatically?”
Yes. If you upload a new CSV that includes additional columns, Paperbox will automatically create those fields on the datasource based on the new headers. After that, you can still adjust the field configuration (like the field “type”) in the frontend (UI).
Which route should you use?
If you want a clean reset of the datasource contents: use Upload a full data version.
If you only need to update some rows (and keep the rest): use Upsert data.
This can be done using both the UI or the API.
Either way, include the new columns in your CSV header, and Paperbox will pick them up.