Skip to content
DashboardGet API key

Create a contact

View .md
POST

Create a contact with one or more channels. An identifier another contact already holds on the same channel is refused (400 duplicate_identifier, with details.conflicts[{channel, identifier, contactId}]); update the existing contact with PATCH /v2/contacts/{contactId} instead.

Authorization

  • Authorizationheaderrequired

    Bearer YOUR_API_KEY. Create a key in the dashboard.

Body

application/json

  • displayNamestring

    Display name for the contact.

    Limitsmax length 200
  • channelsobject[]required

    Communication channels for the contact.

    Limitsmin items 1 · max items 20
    5 properties
    • channelstringrequired

      Channel type.

      One ofsmswhatsappemailtelegraminstagrammessengervoice
    • identifierstringrequired

      Channel identifier (phone number in E.164 format or email address).

    • countryCodestring

      ISO country code for phone numbers.

      Limitsmin length 2 · max length 2
    • labelstring

      Optional label for the channel.

      Limitsmax length 50
    • isPrimaryboolean

      Whether this should be the primary channel for its type.

      Defaultfalse
  • metadataobject

    Arbitrary metadata to associate with the contact.

    1 properties
    • {key}string

Responses

201Created.
  • idstringrequired
  • displayNamestring

    Display name for the contact.

  • phoneNumberstring

    DEPRECATED: Use primaryPhone instead. Primary phone number in E.164 format.

  • primaryPhonestring

    Primary phone number in E.164 format.

  • primaryEmailstring<email>

    Primary email address.

  • countryCodestring
  • profileNamestringnullable

    Contact's WhatsApp profile name. Only available for WhatsApp contacts.

  • whatsappobject

    WhatsApp identity. Present when Zavu has a business-scoped user ID (BSUID) for the contact, and absent otherwise. A contact with a username can be reached under its BSUID, its phone number, or both; they are the same contact. Look one up by BSUID with the bsuid query parameter of the list endpoint.

    2 properties
    • bsuidstringrequired

      Business-scoped user ID. Can be used as to when sending.

    • usernamestring

      The WhatsApp username, when Meta reported one.

  • availableChannelsstring[]required

    List of available messaging channels for this contact.

  • defaultChannelstring

    Preferred channel for this contact.

    One ofsmswhatsapptelegramemailinstagrammessengervoice
  • verifiedbooleanrequired

    Whether this contact has been verified.

  • channelsobject[]

    All communication channels for this contact.

    12 properties
    • idstringrequired
    • channelstringrequired

      Channel type.

      One ofsmswhatsappemailtelegraminstagrammessengervoice
    • identifierstringrequired

      Channel identifier (phone number or email address).

    • countryCodestring

      ISO country code for phone numbers.

    • labelstring

      Optional label for the channel.

    • isPrimarybooleanrequired

      Whether this is the primary channel for its type.

    • verifiedbooleanrequired

      Whether this channel has been verified.

    • metricsobject

      Delivery metrics for this channel.

      5 properties
      • successCountinteger
      • failureCountinteger
      • totalAttemptsinteger
      • avgDeliveryTimeMsnumber
      • lastSuccessAtstring<date-time>
    • lastInboundAtstring<date-time>

      Last time a message was received on this channel.

    • metadataobject
      1 properties
      • {key}string
    • createdAtstring<date-time>required
    • updatedAtstring<date-time>
  • metadataobjectrequired
    1 properties
    • {key}string
  • createdAtstring<date-time>required
  • updatedAtstring<date-time>
400Invalid body (`details.errors`), or `duplicate_identifier`: an identifier is already held by another contact (`details.conflicts`). A phone channel (`sms`, `whatsapp`, `voice`) whose identifier is not E.164 is refused with `details.errors[].path` `["channels", i, "identifier"]` (WhatsApp also takes a BSUID). An `email` identifier that is not an email address is refused the same way. Email identifiers are stored lower-case, and one that differs from another contact's only in case is that contact's address: `duplicate_identifier`.
  • codestringrequired
  • messagestringrequired
  • detailsobject

    Machine-readable context. Keys that mean the same thing everywhere: - errors: present on every 400 invalid_request for an invalid body or query parameter, [{path, message, ...}], path naming the field (["to"], ["contacts", 2, "recipient"], ["limit"]). - recommendation: one sentence saying what to do next. - dashboardUrl: the dashboard screen that fixes it. - connect: on 409 no_channel, the channels this project can connect to reach the recipient, each {type, request, note, available, dashboardUrl?}; request is the exact call (POST /v2/channels with its body, or POST /v2/numbers), or null for a channel connected from the dashboard (WhatsApp, Instagram, Messenger). available: false says why in note (one-way SMS closed until business verification is approved). - address / from: the address the error is about, under the name the request used for it.

    1 properties
    • errorsobject[]
      3 properties
      • pathobject[]required
      • messagestringrequired
      • codestring
401Unauthorized.
  • codestringrequired
  • messagestringrequired
  • detailsobject

    Machine-readable context. Keys that mean the same thing everywhere: - errors: present on every 400 invalid_request for an invalid body or query parameter, [{path, message, ...}], path naming the field (["to"], ["contacts", 2, "recipient"], ["limit"]). - recommendation: one sentence saying what to do next. - dashboardUrl: the dashboard screen that fixes it. - connect: on 409 no_channel, the channels this project can connect to reach the recipient, each {type, request, note, available, dashboardUrl?}; request is the exact call (POST /v2/channels with its body, or POST /v2/numbers), or null for a channel connected from the dashboard (WhatsApp, Instagram, Messenger). available: false says why in note (one-way SMS closed until business verification is approved). - address / from: the address the error is about, under the name the request used for it.

    1 properties
    • errorsobject[]
      3 properties
      • pathobject[]required
      • messagestringrequired
      • codestring