Import or update contacts in bulk

Create-or-update up to 500 contacts in one call — the endpoint for importing a customer list. Each contact is matched against the site’s existing contacts on match_on (email by default, case-insensitively): a match is updated, everything else is created, so re-sending the same batch is safe. Any attribute the CRM has no column for goes in custom_fields as flat key/value pairs, and is auto-declared as a filterable field unless create_missing_fields is false. Tags merge with the contact’s existing tags by default; tags_mode: "replace" overwrites them. Custom fields always merge key-by-key. Use contact_fields_mode: "fill_missing" to enrich contacts while preserving existing native contact values; retry a 409 when a concurrent edit wins. Send dry_run: true first to see the created/updated counts without writing. Two deliberate limits: status (pipeline stage) applies to NEW contacts only — an import never moves an existing contact’s stage — and no contact is ever deleted. Requires scope crm:write.