Upsert up to 500 contacts in one call. Each row finds its existing contact (matchBy, oldest match wins) — by default by its phone number when it has one, otherwise by its email; a row with a number is never matched on an email several people may share — and is updated with the fields it carries (custom fields merged); rows without a match are created (they need firstName). Bad rows are listed in invalid by position — the others still go through. Every created contact fires the contact.created webhook.

Security:

• The organisationId in the URL must match the organisation your JWT was issued for — requests for a different organisation fail with 401.
• Requires CRM_ADMIN, ACCOUNT_OWNER, or CRM_BOT role; other roles receive 403.