Skip to content
DashboardGet API key

List contacts

View .md
GET

List contacts with their channels. A repeated tag means all of them.

Authorization

  • Authorizationheaderrequired

    Bearer YOUR_API_KEY. Create a key in the dashboard.

Query parameters

  • searchstring
    Limitsmax length 200
  • bsuidstring

    Exact WhatsApp business-scoped user ID (e.g. CO.13491208655302741918). Returns the contact that holds it, or an empty list. Combines with phoneNumber and tag as a filter, and cannot be combined with search (400). A value that is not shaped like a BSUID returns 400.

  • tagstring[]
  • limitinteger
    Default50
    Limitsmax 100
  • cursorstring

    Opaque nextCursor from the previous page.

Responses

200Contacts.
  • itemsobject[]required
    15 properties
    • 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>
  • nextCursorstringnullable
400Unknown tag.
  • 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