Met Paperbox datasources kun je gestructureerde referentiedata laden (meestal CSV) die Paperbox kan gebruiken in workflows (bijv. voor matching, verrijking, routering of validaties).
Alle datasource endpoints maken deel uit van de Integration API op https://integration.{ENV}.paperbox.ai (waarbij {ENV} = acc of prd). Authenticatie verloopt via een ondertekende JWT en een API-key verstrekt door Paperbox.
De 3 datasource routes (functies)
1) Een volledige dataversie uploaden (alles vervangen)
Gebruik dit wanneer je de volledige datasource opnieuw wilt uploaden als een verse, complete snapshot. Docs: https://docs.paperbox.ai/integration/api/upload-a-full-data-version-to-a-datasource
Wanneer te gebruiken:
Initiële belading.
Regelmatige "full refresh" integraties (nachtelijke/wekelijkse volledige export).
Grote correcties waarbij het vervangen van alles de eenvoudigste optie is.
2) Data upserten (rijen toevoegen of bijwerken)
Gebruik dit wanneer je incapabel nieuwe rijen wilt toevoegen en bestaande rijen wilt bijwerken zonder de volledige dataset opnieuw te verzenden. Docs: https://docs.paperbox.ai/integration/api/upsert-data-on-a-datasource
Wanneer te gebruiken:
Near-real-time updates (nieuwe/gewijzigde entiteiten).
Dagelijkse delta-exports.
Een datasource synchroon houden zonder volledige reloads.
Let op: Het "upsert"-gedrag is gebaseerd op de geconfigureerde unieke sleutel(s) in Paperbox. Als je niet zeker weet welke sleutel is ingesteld, controleer dan de datasource-instellingen in de UI. Belangrijk: Ontbrekende kolommen leiden tot een 400 Bad Request error; elke upsert vereist alle kolommen.
3) Verwijderingen uploaden (rijen verwijderen)
Gebruik dit wanneer je vermeldingen wilt verwijderen uit een bestaande datasource. Docs: https://docs.paperbox.ai/integration/api/upload-deletes-to-a-datasource
Wanneer te gebruiken:
Entiteiten die verwijderd zijn in het bronsysteem.
Verwijderingen in het kader van GDPR/retentiebeleid (indien van toepassing).
Opschonen van verouderde referentiedata.
Verwachtingen voor CSV-payload
Alle drie de routes accepteren:
content_type = text/csvpayloadals een binaire bestandsupload (jouw CSV-inhoud)
Praktische tips:
Gebruik een header-rij met kolomnamen.
Zorg dat de sleutelkolom(men) (unieke identifier) aanwezig en consistent geformatteerd zijn.
Geef de voorkeur aan stabiele coderingen (UTF-8) en consistente scheidingstekens.
Datasources handmatig uploaden via de UI
Naast de Integration API kunnen datasources ook handmatig via de Paperbox UI worden geüpload. Bij het uploaden via de UI:
Worden alleen JSON-bestanden ondersteund.
Moet de JSON-structuur overeenkomen met het datasource-schema.
Belangrijk: Ontbrekende kolommen leiden tot een 400 Bad Request Error.
Net als bij API-uploads worden nieuwe velden automatisch aangemaakt als ze voorkomen in de geüploade dataset.
Veldtypes en configuratie kunnen achteraf in de frontend (UI) worden aangepast indien nodig.
Handmatige uploads zijn vooral nuttig voor:
Snelle oplossingen of testen.
Kleine datasets.
Eenmalige updates.
Voor geautomatiseerde of terugkerende updates raden we aan de hierboven beschreven Integration API-routes te gebruiken.
FAQ: "Ik moet 1–2 nieuwe velden (kolommen) toevoegen. Kan ik gewoon opnieuw uploaden? Worden de velden automatisch aangemaakt?"
Ja. Als je een nieuwe CSV uploadt die extra kolommen bevat, zal Paperbox deze velden automatisch aanmaken op de datasource op basis van de nieuwe headers. Daarna kun je de veldconfiguratie (zoals het veldtype) nog aanpassen in de frontend (UI).
Welke route moet je gebruiken?
Als je een schone reset van de inhoud wilt: gebruik Upload a full data version.
Als je alleen bepaalde rijen wilt bijwerken (en de rest wilt behouden): gebruik Upsert data.
Dit kan zowel via de UI als de API. In beide gevallen voeg je de nieuwe kolommen toe aan je CSV-header, waarna Paperbox deze automatisch herkent.