Your account, connected to your tools.

Create an API key in Account Settings → API Keys to manage contacts, campaigns, mailboxes and email searches from your integration. Requests use your account's permissions, subscription and credits.

A single email search reserves one credit while the provider is working. The reservation becomes the existing search charge when the provider reports a billable result; a nonbillable no-match or error releases it. Bulk searches reserve their estimated credits before processing.

Finder polling, upload creation and credit balance responses contain success, message and data. Read search states, upload URLs and wallet amounts from data. Paginated responses also include meta where supported.

Create your first key

1. Open Account Settings and choose Create API key in the API Keys card.
2. Give it a name, such as “CRM integration”. Copy the full key from the creation dialog; it is shown once.
3. Store it in your server's secret configuration and send it using the Authorization header.

You can have up to five active keys. Keys do not expire automatically. Revoke a key in Account Settings when an integration stops using it or you need to replace it. Revocation takes effect on subsequent requests.

export MEETBOUND_API_KEY='mb_live_your_key_here'
export MEETBOUND_API_URL='https://api.meetbound.ai/api/v1'

curl --fail-with-body "$MEETBOUND_API_URL/credits/balance" \
  -H "Authorization: Bearer $MEETBOUND_API_KEY"

Responses and limits

Successful JSON responses use {"success":true,"message":"…","data":…}. Use the endpoint reference for each data object, request fields and pagination. All your keys together share a limit of 100 requests per minute. On HTTP 429, wait for the number of seconds in Retry-After before retrying.

Upload a file and import contacts

Create a contact list first using POST /contact-lists, or use a list ID returned by GET /contact-lists. Request an upload URL, upload your file, then pass the returned fileUrl to the import endpoint.

# 1. Request a URL for this account and import purpose.
FILE_SIZE=$(wc -c < contacts.csv | tr -d ' ')
UPLOAD_REQUEST=$(jq -n --argjson size "$FILE_SIZE" \
  '{fileName:"contacts.csv",contentType:"text/csv",purpose:"contacts",sizeBytes:$size}')
UPLOAD_JSON=$(curl --fail-with-body "$MEETBOUND_API_URL/files/uploads" \
  -H "Authorization: Bearer $MEETBOUND_API_KEY" \
  -H 'Content-Type: application/json' \
  --data "$UPLOAD_REQUEST")

UPLOAD_URL=$(printf '%s' "$UPLOAD_JSON" | jq -r '.data.uploadUrl')
FILE_URL=$(printf '%s' "$UPLOAD_JSON" | jq -r '.data.fileUrl')

# 2. Upload directly to storage using the same Content-Type.
curl --fail-with-body -X PUT "$UPLOAD_URL" \
  -H 'Content-Type: text/csv' -H "Content-Length: $FILE_SIZE" --upload-file contacts.csv

# 3. Import into your list.
IMPORT_JSON=$(jq -n --arg url "$FILE_URL" --arg list 'your_list_id' \
  '{fileUrl:$url,listId:$list}')
curl --fail-with-body "$MEETBOUND_API_URL/contacts/import" \
  -H "Authorization: Bearer $MEETBOUND_API_KEY" \
  -H 'Content-Type: application/json' --data "$IMPORT_JSON"

Upload URLs last five minutes. Import files must be at most 10 MB. Use the matching purpose: contacts, email-finder or email-accounts. The returned file URL belongs to your account and that purpose. For contact imports, include an email column; additional columns become contact metadata. Consult the endpoint reference for mailbox import columns.

Start an email search and poll its result

A single search returns data.searchId. Poll the search endpoint every few seconds until data.state is completed or failed. A completed search may contain no email match.

SEARCH_JSON=$(curl --fail-with-body "$MEETBOUND_API_URL/email-finder/single-search" \
  -H "Authorization: Bearer $MEETBOUND_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"firstName":"Ada","lastName":"Lovelace","domainOrCompany":"example.com"}')
SEARCH_ID=$(printf '%s' "$SEARCH_JSON" | jq -r '.data.searchId')

curl --fail-with-body "$MEETBOUND_API_URL/email-finder/searches/$SEARCH_ID" \
  -H "Authorization: Bearer $MEETBOUND_API_KEY"

For bulk searches, upload a CSV with purpose email-finder. Put first name, last name and company/domain in the first three columns. Call POST /email-finder/estimate with the uploaded fileUrl to check the estimate, then POST /email-finder/bulk-search with fileUrl and fileName to start. The creation response includes data.id: use that database ID in GET /email-finder/bulk-searches/{id}, then fetch results from GET /email-finder/bulk-search-result/{id} when completed. Keep polling spaced out and respect Retry-After.

Export email-finder results

Call POST /email-finder/export-history with {"id":"history_or_bulk_id","type":"single"} or type bulk. The response contains a downloadable URL. Download it while the URL is valid. Export requests and searches use the same account and ownership checks as your other API calls.

Partner integrations

The partner reference describes partner onboarding and JWT access. Customer API keys operate on their owner's account. Partner provisioning requires partner permissions; user-token exchange requires an existing partner JWT.