Import contacts from a CSV
Add or update many people at once from a CSV, given as text (csv) or as a base64 file (file, up to 12 MB, about 100,000 rows). Rows matching an existing contact's phone, WhatsApp, email or document update that contact; the rest create new ones. Returns a task at once: follow it with get_task (processedRows of totalRows, then created, updated and rejected counts with the first 100 row errors). cancel_task stops it after the current batch; a failed import resumes with retry_task within 7 days. Fails with IMPORT_FILE_INVALID when the file is not UTF-8 and IMPORT_FILE_TOO_LARGE above 12 MB.
- Scope:
raiz:contacts:write - Credentials: an API key, a client-credentials token or a person's access token
- Effect: writes; not idempotent: check the outcome before you retry
- Limits: request body up to 16 MB, response up to 1 MB
- CLI:
arbol raiz contacts import· MCP tool:raiz_contacts_import
https://api.getarbol.com/v1/raiz/contacts/importAuthorization
Request body JSON required
- csvoptionalstring
The CSV as text. UTF-8 CSV with a header row (
,,;or tab). Recognized columns:given_name,family_name,phone,whatsapp,email,document_type,document_number,summary; any other column is stored as metadata, or as a fact when its header is an active contact definition's key. Rows whose phone, WhatsApp, email or document matches an existing contact update that contact. Givecsvorfile, not both.maxLength: 12000000 · minLength: 1 - fileoptionalobject
The CSV file as read from disk, in base64, as Knowledge files are sent. UTF-8 CSV with a header row (
,,;or tab). Recognized columns:given_name,family_name,phone,whatsapp,email,document_type,document_number,summary; any other column is stored as metadata, or as a fact when its header is an active contact definition's key. Rows whose phone, WhatsApp, email or document matches an existing contact update that contact.
Returns
200
Successful operation.
413
REQUEST_TOO_LARGE: The request exceeds the allowed size.IMPORT_FILE_TOO_LARGE: The import file is larger than 12 MB. Split it into several files.
422
IMPORT_FILE_INVALID: The import file is not valid base64 of UTF-8 text. Save the spreadsheet as CSV UTF-8 and try again.
502
OUTCOME_UNKNOWN: The operation may have been applied; check its result before repeating it.
503
UPSTREAM_UNAVAILABLE: The upstream service could not complete the request.INTEGRATIONS_UNAVAILABLE: The organization's integrations cannot be read right now. Try again shortly.