curl -X POST https://api.ibubbl.com/v1/contacts/c8a1f4e2-3b9d-4f7c-a8e5-1d2c3b4a5e6f/block \
-H "Authorization: Bearer $IBUBBL_API_KEY"
const contactId = "c8a1f4e2-3b9d-4f7c-a8e5-1d2c3b4a5e6f";
const res = await fetch(`https://api.ibubbl.com/v1/contacts/${contactId}/block`, {
method: "POST",
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}`);
console.log(data.blocked, data.blocked_at);
import os
import requests
API_KEY = os.environ["IBUBBL_API_KEY"]
contact_id = "c8a1f4e2-3b9d-4f7c-a8e5-1d2c3b4a5e6f"
res = requests.post(
f"https://api.ibubbl.com/v1/contacts/{contact_id}/block",
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=10,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['detail']['error']}")
print(data["blocked"], data["blocked_at"])
{
"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": true,
"blocked_at": "2026-11-11T09:20:44.902+00:00",
"created_at": "2026-11-05T14:23:45.123+00:00"
}
{
"detail": {
"error": "not_found",
"message": "Contact not found"
}
}
Block a contact
A block is yours, on this contact: sends to them return 422 contact_blocked (group conversations they’re in are not affected). Their inbound messages are still stored and still fire message.inbound, but don’t mark the conversation unread, notify anyone or start workflows. Unlike an opt-out, a block fires no webhook and can be undone with DELETE /v1/contacts/{id}/block. A contact deleted and created again starts unblocked.
Idempotent: blocking a blocked contact answers 200 and keeps the original blocked_at.
curl -X POST https://api.ibubbl.com/v1/contacts/c8a1f4e2-3b9d-4f7c-a8e5-1d2c3b4a5e6f/block \
-H "Authorization: Bearer $IBUBBL_API_KEY"
const contactId = "c8a1f4e2-3b9d-4f7c-a8e5-1d2c3b4a5e6f";
const res = await fetch(`https://api.ibubbl.com/v1/contacts/${contactId}/block`, {
method: "POST",
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}`);
console.log(data.blocked, data.blocked_at);
import os
import requests
API_KEY = os.environ["IBUBBL_API_KEY"]
contact_id = "c8a1f4e2-3b9d-4f7c-a8e5-1d2c3b4a5e6f"
res = requests.post(
f"https://api.ibubbl.com/v1/contacts/{contact_id}/block",
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=10,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['detail']['error']}")
print(data["blocked"], data["blocked_at"])
{
"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": true,
"blocked_at": "2026-11-11T09:20:44.902+00:00",
"created_at": "2026-11-05T14:23:45.123+00:00"
}
{
"detail": {
"error": "not_found",
"message": "Contact not found"
}
}
Block a contact
Method:POST | Endpoint: /v1/contacts/{contact_id}/block
Description: Stop one-to-one messages to a contact until you unblock them. A block is your choice and can be undone; an opt-out is the contact’s and can’t. See Block or opt out.
Authentication: API key in the Authorization header: Authorization: Bearer ib_pk_<64 hex>. Create keys in the dashboard under Settings → API access.
Request Body
None. The path parametercontact_id is the contact’s ID (a UUID).
What a block does
- Sends are refused. One-to-one sends to the contact, from the API, the dashboard or an automation, return
422 contact_blocked. Group conversations they’re in are not affected. - Their messages still arrive. Inbound messages from them are stored and still fire
message.inbound, but they don’t mark the conversation unread, notify your team, or start workflows. - No webhook fires, for the block or the unblock.
- It’s safe to call twice. Blocking a blocked contact answers
200and keeps the originalblocked_at. - It belongs to this contact. If the contact is deleted and the number later comes back as a new contact, the new one isn’t blocked.
curl -X POST https://api.ibubbl.com/v1/contacts/c8a1f4e2-3b9d-4f7c-a8e5-1d2c3b4a5e6f/block \
-H "Authorization: Bearer $IBUBBL_API_KEY"
const contactId = "c8a1f4e2-3b9d-4f7c-a8e5-1d2c3b4a5e6f";
const res = await fetch(`https://api.ibubbl.com/v1/contacts/${contactId}/block`, {
method: "POST",
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}`);
console.log(data.blocked, data.blocked_at);
import os
import requests
API_KEY = os.environ["IBUBBL_API_KEY"]
contact_id = "c8a1f4e2-3b9d-4f7c-a8e5-1d2c3b4a5e6f"
res = requests.post(
f"https://api.ibubbl.com/v1/contacts/{contact_id}/block",
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=10,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['detail']['error']}")
print(data["blocked"], data["blocked_at"])
{
"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": true,
"blocked_at": "2026-11-11T09:20:44.902+00:00",
"created_at": "2026-11-05T14:23:45.123+00:00"
}
{
"detail": {
"error": "not_found",
"message": "Contact not found"
}
}
Responses
200 OK The contact, withblocked: true.
{
"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": true,
"blocked_at": "2026-11-11T09:20:44.902+00:00",
"created_at": "2026-11-05T14:23:45.123+00:00"
}
{
"detail": {
"error": "unauthorized",
"message": "Invalid or revoked API key"
}
}
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"
}
}
message is then Account is cancelled). Every API-key endpoint returns this.
404 Not Found
{
"detail": {
"error": "not_found",
"message": "Contact not found"
}
}
Authorizations
Bearer API key. Format: Authorization: Bearer ib_pk_<64 hex> (70 characters). Generate keys from Dashboard → Settings → API Access.
Path Parameters
Response
The contact, now blocked.
Unique contact identifier (UUID).
Contact's phone number as first seen. Usually E.164; a contact first created by an inbound SMS can carry the sender's bare national form (e.g. 4155551234). Upserting any form of the same number returns this contact.
True if this person has opted out: a STOP reply, a rep in the dashboard, a Do Not Disturb in your connected GoHighLevel account, or POST /v1/contacts/{id}/opt-out. When true, every send to this contact returns 422 contact_opted_out. An opt-out can't be undone, and it belongs to the number: a contact deleted and created again is still opted out.
ISO 8601 UTC timestamp the contact was created.
IANA timezone used for this contact's sending hours, or null if not set yet. When it is null and the number is a US or Canadian one, iBubbl infers the zone from the area code and saves it here when the contact's first message is processed; otherwise your account's timezone is used. Once set, an upsert never replaces it, so pass timezone on the first upsert, before you send, or change it with PATCH.
The contact's tag names, sorted case-insensitively.
ISO 8601 UTC timestamp of the opt-out, or null.
True if you blocked this contact (dashboard or POST /v1/contacts/{id}/block). Sends to them return 422 contact_blocked until you unblock them. Unlike an opt-out, a block is yours to undo, and it fires no webhook.
ISO 8601 UTC timestamp of the block, or null.