Upsert a contact asynchronously. (Strongly recommended)

Upsert a contact asynchronously in the Qomon database.

When upserting, the system tries to find an existing contact to update using the following strategy (in order). If no match is found, a new contact is created.

1. Match by ID

• If an id is provided and matches an existing contact, that contact will be updated (can be a contact ID or nationbuilder ID).

2. Match by email + name

• If no ID is provided (or it didn’t match), the system searches for contacts with the same mail.
• Among the results, if firstname is provided, it must also match. If surname is provided, it must also match. (An empty value for firstname or surname means the field will not be used for matching.)
• If a match is found, that contact is updated.

3. Match by surname + firstname + birthdate + address

• If no match was found by email, and a surname is provided, the system searches for contacts with the same surname.
• Among the results, firstname must match.
• If both the incoming and the existing contact have a birthdate, they must match exactly.
• If both contacts have an address, the city or postalcode must match. If no birthdate comparison was made, the street must also match.
• If all the above conditions are met, that contact is updated.

4. No match found

• If none of the above strategies found a match, a new contact is created.

⚠️ If the id or label of an advanced field, or the value (for non-free-text fields), does not exist, the contact will not be updated or created. Errors will not be logged.

💡 For consents, level_of_support, custom_fields, survey, tasks:

• See details in above description.
• Found id, label, value in GET /forms/ endpoint.