Bird

Sync contacts to Bird (formerly MessageBird) for omnichannel messaging campaigns via email, SMS, and WhatsApp. Zeotap keeps your Bird contact records and list memberships in sync with your warehouse data, enabling targeted campaigns with up-to-date customer attributes.

Prerequisites

• A Bird account with API access enabled
• A Bird API access key
• Your Bird workspace ID

Authentication

Bird uses Access Key authentication.

1. Log in to the Bird Dashboard 
2. Navigate to Settings > Developers > API Access
3. Click Create Access Key and copy the generated key
4. Paste it into the Access Key field in Zeotap

Configuration

To find your Workspace ID, navigate to Settings > Organization in the Bird dashboard. The workspace ID is displayed in the URL or workspace settings panel.

Target Settings

To find your List ID, navigate to Contacts > Lists in the Bird dashboard. Click on a list to view its details; the list ID is shown in the URL.

Supported Operations

Sync Modes

Bird’s contact API is inherently upsert: a single PATCH-by-identifier call creates a contact when the identifier is new and updates it when the identifier already exists. There are no separate insert-only or update-only endpoints.

Audience Sync Modes

Features

• Field Mapping: Yes
• Schema Introspection: No

Required Mapping Fields

Default Destination Fields

identifier_key, identifier_value, displayName, firstName, lastName, countryCode, language

Bird identifies contacts by their identifiers (email, phone, etc.) rather than a single email field. When syncing, you must map both the identifier type and value. All other mapped fields (standard or custom) are sent inside Bird’s contact attributes object.

How It Works

Contact Sync (Upsert Mode)

1. For each row, Zeotap extracts the identifier_key and identifier_value
2. A PATCH request is sent to PATCH /workspaces/{workspaceId}/contacts/identifiers/{identifierKey}/{identifierValue}
3. If the identifier exists, the contact is updated; if not, a new contact is created
4. All other mapped fields (displayName, firstName, countryCode, language, custom attributes, etc.) are sent nested inside the attributes object, as required by the Bird API

Audience Sync (Add/Remove/Mirror)

• Add: Contacts are upserted, then added to the list via POST /workspaces/{workspaceId}/lists/{listId}/contacts (max 100 per request)
• Remove: Contacts are removed from the list via DELETE /workspaces/{workspaceId}/lists/{listId}/contacts (max 100 per request)
• Mirror: Added/changed contacts are upserted and added to the list; removed contacts are unlinked from the list

Rate Limits

Zeotap automatically retries on 429 Too Many Requests responses with exponential backoff.

Best Practices

• Use upsert mode for most contact syncs to handle both new and existing contacts seamlessly
• Configure a List ID for audience syncs to manage list membership automatically
• Map identifier fields carefully — identifier_key must match Bird’s supported types: emailaddress, phonenumber, facebook, wechat, line, telegram, instagram, twitter
• Use international phone format (e.g., +31600000000) for phone number identifiers
• Set the countryCode field using ISO 3166-1 alpha-2 codes (e.g., NL, US, DE)
• Set the language field using ISO 639-1 codes (e.g., en, nl, de)

Troubleshooting

Authentication failed: invalid access key

Ensure your access key is correct and has not been revoked. Generate a new key from Settings > Developers > API Access in the Bird dashboard.

Workspace not found (404)

Verify the workspace ID is correct. The workspace ID is a UUID visible in your Bird dashboard URL or workspace settings.

Missing identifier_key or identifier_value

Both identifier_key and identifier_value must be mapped. The identifier_key specifies the type (e.g., emailaddress) and identifier_value provides the actual contact identifier.

Unsupported identifier type

Bird supports these identifier types: emailaddress, phonenumber, facebook, wechat, line, telegram, instagram, twitter. Ensure your identifier_key matches one of these values.

List ID not found

Verify the list ID exists in your Bird workspace. Navigate to Contacts > Lists in the Bird dashboard and check the list ID in the URL.

Contacts not appearing in list

Ensure the List ID target setting is configured. Contacts must be upserted before they can be added to a list. If using audience sync modes, Zeotap handles this automatically.

Rate limit exceeded (429 errors)

Zeotap retries automatically with exponential backoff. If errors persist, contact Bird support to request higher rate limits or reduce the sync frequency.

Phone number format rejected

Phone numbers must include the country code in international format (e.g., +31600000000). Bird does not accept local phone number formats without country codes.