# Sent as ?limit=50&search=sam%20rivera&tag=VIP
curl -G https://api.ibubbl.com/v1/contacts \
  -H "Authorization: Bearer $IBUBBL_API_KEY" \
  --data-urlencode "limit=50" \
  --data-urlencode "search=sam rivera" \
  --data-urlencode "tag=VIP"

# Next page: add the id of the last contact you received.
#   --data-urlencode "starting_after=c8a1f4e2-3b9d-4f7c-a8e5-1d2c3b4a5e6f"

const params = new URLSearchParams({
  limit: "50",
  search: "sam rivera",
  tag: "VIP",
});

const res = await fetch(`https://api.ibubbl.com/v1/contacts?${params}`, {
  headers: { Authorization: `Bearer ${process.env.IBUBBL_API_KEY}` },
  signal: AbortSignal.timeout(10_000),
});

const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.detail?.error}`);
for (const contact of data.data) {
  console.log(contact.id, contact.phone, contact.first_name, contact.opted_out);
}
// More? Repeat with starting_after = data.data[data.data.length - 1].id
console.log("has_more:", data.has_more);

import os

import requests

API_KEY = os.environ["IBUBBL_API_KEY"]

res = requests.get(
    "https://api.ibubbl.com/v1/contacts",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={"limit": 50, "search": "sam rivera", "tag": "VIP"},
    timeout=10,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {data['detail']['error']}")
for contact in data["data"]:
    print(contact["id"], contact["phone"], contact["first_name"], contact["opted_out"])
# More? Repeat with starting_after = data["data"][-1]["id"]
print("has_more:", data["has_more"])

{
  "data": [
    {
      "id": "c8a1f4e2-3b9d-4f7c-a8e5-1d2c3b4a5e6f",
      "phone": "+14155551234",
      "first_name": "Sam",
      "last_name": "Rivera",
      "email": "sam@example.com",
      "city": "Brooklyn",
      "state": "NY",
      "timezone": "America/New_York",
      "tags": [
        "Spring promo",
        "VIP"
      ],
      "opted_out": false,
      "opted_out_at": null,
      "blocked": false,
      "blocked_at": null,
      "created_at": "2026-11-05T14:23:45.123+00:00"
    }
  ],
  "has_more": false
}

{
  "detail": {
    "error": "invalid_cursor",
    "message": "starting_after is not the id of one of your items"
  }
}

{
  "detail": {
    "error": "rate_limited",
    "message": "Too many list requests; wait 18s (limit 120 a minute per account)."
  }
}

Contacts

List contacts

List your contacts, newest first. Deleted contacts are never listed.

Results are paginated: has_more tells you whether there is another page, and you get it by passing the id of the last contact as starting_after. Pages are stable while contacts are added: nothing is skipped or repeated. See Pagination.

Filters combine with AND. A filter value that matches nothing (including a tag you don’t have) returns an empty page. An unknown or repeated query parameter returns 422 validation_error.

Lists allow 120 requests a minute per account, across all your API keys and all lists. Over that, the answer is 429 rate_limited with a Retry-After header in seconds.

GET

contacts

# Sent as ?limit=50&search=sam%20rivera&tag=VIP
curl -G https://api.ibubbl.com/v1/contacts \
  -H "Authorization: Bearer $IBUBBL_API_KEY" \
  --data-urlencode "limit=50" \
  --data-urlencode "search=sam rivera" \
  --data-urlencode "tag=VIP"

# Next page: add the id of the last contact you received.
#   --data-urlencode "starting_after=c8a1f4e2-3b9d-4f7c-a8e5-1d2c3b4a5e6f"

const params = new URLSearchParams({
  limit: "50",
  search: "sam rivera",
  tag: "VIP",
});

const res = await fetch(`https://api.ibubbl.com/v1/contacts?${params}`, {
  headers: { Authorization: `Bearer ${process.env.IBUBBL_API_KEY}` },
  signal: AbortSignal.timeout(10_000),
});

const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.detail?.error}`);
for (const contact of data.data) {
  console.log(contact.id, contact.phone, contact.first_name, contact.opted_out);
}
// More? Repeat with starting_after = data.data[data.data.length - 1].id
console.log("has_more:", data.has_more);

import os

import requests

API_KEY = os.environ["IBUBBL_API_KEY"]

res = requests.get(
    "https://api.ibubbl.com/v1/contacts",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={"limit": 50, "search": "sam rivera", "tag": "VIP"},
    timeout=10,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {data['detail']['error']}")
for contact in data["data"]:
    print(contact["id"], contact["phone"], contact["first_name"], contact["opted_out"])
# More? Repeat with starting_after = data["data"][-1]["id"]
print("has_more:", data["has_more"])

{
  "data": [
    {
      "id": "c8a1f4e2-3b9d-4f7c-a8e5-1d2c3b4a5e6f",
      "phone": "+14155551234",
      "first_name": "Sam",
      "last_name": "Rivera",
      "email": "sam@example.com",
      "city": "Brooklyn",
      "state": "NY",
      "timezone": "America/New_York",
      "tags": [
        "Spring promo",
        "VIP"
      ],
      "opted_out": false,
      "opted_out_at": null,
      "blocked": false,
      "blocked_at": null,
      "created_at": "2026-11-05T14:23:45.123+00:00"
    }
  ],
  "has_more": false
}

{
  "detail": {
    "error": "invalid_cursor",
    "message": "starting_after is not the id of one of your items"
  }
}

{
  "detail": {
    "error": "rate_limited",
    "message": "Too many list requests; wait 18s (limit 120 a minute per account)."
  }
}

List contacts

Method: GET | Endpoint: /v1/contacts Description: List your contacts, newest first, with their tags, opt-out and block state. Search by name, email or phone, or filter by tag, opt-out or block. Deleted contacts are never listed. Authentication: API key in the Authorization header: Authorization: Bearer ib_pk_<64 hex>. Create keys in the dashboard under Settings → API access.

Query parameters

All optional. Filters combine with AND.

Parameter	Type	Description
`limit`	integer	How many contacts to return, `1` to `100`. Defaults to `50`. Outside that range is `422 validation_error`, not rounded.
`starting_after`	string (UUID)	The `id` of the last contact on the page you already have. Returns the contacts after it. Leave it out for the first page. See Pagination.
`search`	string	Contacts matching every word, ignoring case, as part of the first name, last name, email or phone number: `sam rivera` finds Sam Rivera, and `example.com` finds everyone with an email there. A word written like a phone number also matches by its digits, so `415-555-1234` and `(415)` find `+14155551234`. `%` and `_` match themselves. The characters `"`, `\` and `*` are ignored. Up to 100 characters.
`tag`	string	Contacts with this tag, matched ignoring case and outer spaces: `vip` finds contacts tagged `VIP`. If you have two tags that differ only by case, contacts with either are listed (once each).
`opted_out`	boolean	`true`: only contacts who have opted out. `false`: only the others.
`blocked`	boolean	`true`: only contacts you’ve blocked. `false`: only the others.

Any other query parameter, or one given twice, returns 422 validation_error naming it. A misspelt startingAfter is refused instead of quietly returning the first page again. A filter that matches nothing returns an empty page, including a tag you don’t have. A contact deleted since you received it is no longer a valid starting_after (422 invalid_cursor): restart from the first page. Rate limit: 120 list requests per 60 seconds per account, across all your API keys and all list endpoints. Over that, you get 429 rate_limited with a Retry-After header; see Rate limits.

# Sent as ?limit=50&search=sam%20rivera&tag=VIP
curl -G https://api.ibubbl.com/v1/contacts \
  -H "Authorization: Bearer $IBUBBL_API_KEY" \
  --data-urlencode "limit=50" \
  --data-urlencode "search=sam rivera" \
  --data-urlencode "tag=VIP"

# Next page: add the id of the last contact you received.
#   --data-urlencode "starting_after=c8a1f4e2-3b9d-4f7c-a8e5-1d2c3b4a5e6f"

const params = new URLSearchParams({
  limit: "50",
  search: "sam rivera",
  tag: "VIP",
});

const res = await fetch(`https://api.ibubbl.com/v1/contacts?${params}`, {
  headers: { Authorization: `Bearer ${process.env.IBUBBL_API_KEY}` },
  signal: AbortSignal.timeout(10_000),
});

const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.detail?.error}`);
for (const contact of data.data) {
  console.log(contact.id, contact.phone, contact.first_name, contact.opted_out);
}
// More? Repeat with starting_after = data.data[data.data.length - 1].id
console.log("has_more:", data.has_more);

import os

import requests

API_KEY = os.environ["IBUBBL_API_KEY"]

res = requests.get(
    "https://api.ibubbl.com/v1/contacts",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={"limit": 50, "search": "sam rivera", "tag": "VIP"},
    timeout=10,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {data['detail']['error']}")
for contact in data["data"]:
    print(contact["id"], contact["phone"], contact["first_name"], contact["opted_out"])
# More? Repeat with starting_after = data["data"][-1]["id"]
print("has_more:", data["has_more"])

{
  "data": [
    {
      "id": "c8a1f4e2-3b9d-4f7c-a8e5-1d2c3b4a5e6f",
      "phone": "+14155551234",
      "first_name": "Sam",
      "last_name": "Rivera",
      "email": "sam@example.com",
      "city": "Brooklyn",
      "state": "NY",
      "timezone": "America/New_York",
      "tags": [
        "Spring promo",
        "VIP"
      ],
      "opted_out": false,
      "opted_out_at": null,
      "blocked": false,
      "blocked_at": null,
      "created_at": "2026-11-05T14:23:45.123+00:00"
    }
  ],
  "has_more": false
}

{
  "detail": {
    "error": "invalid_cursor",
    "message": "starting_after is not the id of one of your items"
  }
}

{
  "detail": {
    "error": "rate_limited",
    "message": "Too many list requests; wait 18s (limit 120 a minute per account)."
  }
}

Responses

200 OK data holds up to limit contacts, newest first: by created_at (when the contact was created), then by id for contacts created in the same microsecond. Each item is exactly what Retrieve a contact returns for that contact. has_more is true when more contacts match; to get them, repeat the request with starting_after set to the id of the last item in data. An empty data comes with has_more: false.

{
  "data": [
    {
      "id": "c8a1f4e2-3b9d-4f7c-a8e5-1d2c3b4a5e6f",
      "phone": "+14155551234",
      "first_name": "Sam",
      "last_name": "Rivera",
      "email": "sam@example.com",
      "city": "Brooklyn",
      "state": "NY",
      "timezone": "America/New_York",
      "tags": [
        "Spring promo",
        "VIP"
      ],
      "opted_out": false,
      "opted_out_at": null,
      "blocked": false,
      "blocked_at": null,
      "created_at": "2026-11-05T14:23:45.123+00:00"
    }
  ],
  "has_more": false
}

401 Unauthorized

{
  "detail": {
    "error": "unauthorized",
    "message": "Invalid or revoked API key"
  }
}

Other message values: Authorization Bearer token required, API key required (use Authorization: Bearer ib_pk_…), Invalid API key format, Customer account not found. 403 Forbidden

{
  "detail": {
    "error": "forbidden",
    "message": "Account is suspended"
  }
}

Your iBubbl account is suspended or cancelled (message is then Account is cancelled). Every API-key endpoint returns this. 422 Unprocessable Entity

{
  "detail": {
    "error": "validation_error",
    "message": "Unknown query parameter: startingAfter. Allowed: blocked, limit, opted_out, search, starting_after, tag"
  }
}

validation_error: a query parameter is unknown, repeated or invalid (limit outside 1–100, a starting_after that isn’t a UUID, opted_out or blocked other than true / false, an empty or over-long search or tag, or a search with nothing left to match once ", \ and * are removed). invalid_cursor: starting_after is a UUID but not the ID of one of your contacts, or that contact has been deleted. 429 Too Many Requests

Retry-After: 18

{
  "detail": {
    "error": "rate_limited",
    "message": "Too many list requests; wait 18s (limit 120 a minute per account)."
  }
}

Your account made more than 120 list requests in the last 60 seconds. Retry-After is the number of whole seconds until the oldest of them stops counting. Wait that long, then send the same request again; the refused request didn’t count. The limit is checked after the API key, so a bad key is still 401.

Authorizations

Authorization

string

header

required

Bearer API key. Format: Authorization: Bearer ib_pk_<64 hex> (70 characters). Generate keys from Dashboard → Settings → API Access.

Query Parameters

limit

integer

default:50

How many items to return, 1 to 100. Defaults to 50.

Required range: 1 <= x <= 100

starting_after

string<uuid> | null

The id of the last item on the page you already have. Returns the items that come after it, in the same order. Leave it out for the first page. An id that isn't one of yours returns 422 invalid_cursor. A contact deleted since is no longer a valid cursor.

string | null

Only contacts matching every word, case-insensitively, as part of the first name, last name, email or phone number: sam rivera finds Sam Rivera. A word written like a phone number also matches by its digits, so 415-555-1234 finds +14155551234. The characters ", \ and * are ignored. Up to 100 characters.

Required string length: 1 - 100

opted_out

boolean | null

true: only opted-out contacts. false: only the others.

blocked

boolean | null

true: only blocked contacts. false: only the others.

tag

string | null

Only contacts with this tag, matched trimmed and case-insensitively (vip matches VIP).

Required string length: 1 - 64

Response

A page of contacts.

data

Contact · object[]

required

Up to limit contacts, newest first: by created_at, then by id for contacts created in the same microsecond.

Show child attributes

has_more

boolean

required

Whether more contacts match after the last one in data. To get them, repeat the request with starting_after set to that contact's id.

Get started

Concepts

Guides

Webhooks

API reference

Resources

List contacts

List contacts

Query parameters

Responses

Authorizations

Query Parameters

Response

​List contacts

​Query parameters

​Responses

Authorizations

Query Parameters

Response

List contacts

Query parameters

Responses