Create a recipient

Creates a recipient, optionally together with the contacts to reach them on.

A recipient without a contact receives NOTHING. It still appears in listings, still joins groups, still sits in escalation chains — and every alert addressed to it goes nowhere, silently. Send contacts in this call and that state never exists: the recipient and its channels are written in one transaction, so a client that dies halfway leaves nothing behind, and a client that forgets the second call cannot happen. If you create without contacts, the response says so — data.delivery.deliverable is false and a top-level warnings entry names the endpoint that fixes it.

Contacts are a list because one on-call person usually needs more than one channel; each entry takes exactly the same fields as POST /recipients/{recipient}/contacts (same rules, same normalisation, same errors), and a recipient holds at most one contact per type, so two entries of the same type are rejected before anything is written. At most one entry may set is_primary.

Retries are safe. Repeating the call with a name that already exists returns the existing recipient with 200 instead of creating a duplicate. Contacts follow the same rule: an entry whose type the recipient already has, with the same address, is treated as already done and changes nothing. Same type but a DIFFERENT address is a real conflict and answers 409 — the address you asked for is not the address stored, and pretending otherwise would report a success that did not happen; fix it through the contact endpoints. Only the address is compared: is_primary and label of an existing contact are left alone. For internal_sip, repeating __create_new__ when an extension is already assigned is a no-op rather than a second allocation.

A blank name is never matched against existing recipients — every blank call creates a new row.