Contacts and consent

Keep contacts in sync#

PUT /v1/contacts/by-identity is the call integrations use. It finds the contact that has the phone number, updates it with the fields you send, or creates it, and it is safe to repeat: the same call twice leaves the same contact.

curl -sS -X PUT "$MYCOMM_URL/v1/contacts/by-identity" \
  -H "Authorization: Bearer $MYCOMM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identity": {"type": "phone", "address": "+923001234567"},
    "first_name": "Amina",
    "last_name": "Khan",
    "language": "en",
    "custom_fields": {"plan": "gold"}
  }'

On update, top-level fields you send replace the old value and null empties one; custom_fields merges key by key and a null value removes a key. add_to_group_ids only adds memberships. The number is normalised to E.164 using the account's country.

For many at once, POST /v1/contacts/bulk takes up to 1,000 contacts and returns a result per row (created, updated or rejected, with the error of a rejected row), so one bad number does not stop the rest.

Import a CSV#

POST /v1/imports takes a UTF-8 CSV with a header row (up to 20 MB and 200,000 rows) as multipart/form-data, with type (contacts_csv or suppressions_csv), the file and options. Map your columns to MyComm fields in options.mapping, choose what happens to a contact that already exists with existing (fill_empty, overwrite or skip), and assert consent with consent_assertion when the file is a marketing audience. The import is processed in the background: poll GET /v1/imports/{id} or wait for import.completed or import.failed.

Groups, smart lists and custom fields#

• Groups are fixed lists you add contacts to and remove them from.
• Smart lists are saved filters that stay up to date; preview a filter before you save it.
• Custom fields are definitions you create first (POST /v1/contact-fields), then fill in per contact in custom_fields; templates can use them as {{ plan }}.

Opt-outs and consent#

An opt-out is enforced in one place for everything that sends: the API, campaigns and automation all read the same list.

• A recipient who texts a stop word is opted out automatically and, by default, gets one confirmation reply.
• POST /v1/suppressions adds a number yourself; POST /v1/contacts/{id}/opt-out opts a contact out everywhere; POST /v1/suppressions/{id}/remove takes one off. GET /v1/suppressions/check?address=... tells you whether a number is suppressed before you try to send.
• A marketing send to an opted-out number is refused with RECIPIENT_OPTED_OUT; a transactional message is not.
• An upsert never clears an opt-out: only the person, or an explicit removal by you, does.
• Record where consent came from. GET /v1/consent-events is the append-only trail of opt-ins and opt-outs with their method and time, and it outlives the suppression it records.

Subscribe to contact.created, contact.updated, contact.deleted, contact.opted_out and contact.opted_in to keep your own system current. See the event catalogue.