Skip to content
Docs

Bulk sends to contacts on one account (Messenger / Instagram within the 24 h window or with HUMAN_AGENT, X, Bluesky…), rate limited per channel with per-recipient delivery status. Each recipient is one message.

Base URLhttps://api.socialit.com/v1AuthenticationErrorsRate limits11 endpointsMCP toolset broadcasts

List broadcasts

GET/broadcasts

Access: readZernio: GET /v1/broadcasts

Try it with MCPAsk your agent to call list-broadcasts (toolset broadcasts)Set up MCP

Query parameters

pageintegerdefault: 1

Page number

≥ 1

limitintegerdefault: 20

Items per page (max 100)

1–100

sortstring

created_atscheduled_atname

orderstring

ascdesc

matchstring

Combine filters with AND (default) or OR

allor

profile_idstring
account_idstring
statusstring
platformstring

Returns object

objectstringrequired

list

dataarray of objectrequired
Show 26 item attributes
objectstring

broadcast

idstring
profile_idstring | null
account_idstring | null
account_namestring | null
platformstring
namestring
descriptionstring | null
statusstring

draftscheduledsendingcompletedfailedcancelled

messageobject
Show 3 child attributes
textstring | null
attachmentsarray of object
Show 3 item attributes
typestring
urlstring
filenamestring | null
message_tagstring | null
segment_filtersobject | null
Show 5 child attributes
tagsarray of string
tags_matchstring
exclude_tagsarray of string
is_subscribedboolean
custom_fieldsobject
message_previewstring | null
rate_limit_per_minuteinteger | null
scheduled_atstring (date-time) | null
started_atstring (date-time) | null
completed_atstring (date-time) | null
recipient_countinteger
pending_countinteger
sent_countinteger
delivered_countinteger
read_countinteger
failed_countinteger
skipped_countinteger
last_errorstring | null
created_atstring (date-time) | null
updated_atstring (date-time) | null
pageintegerrequired
limitintegerrequired
totalinteger | null
has_morebooleanrequired
next_page_urlstring | null
previous_page_urlstring | null

Responses

  • 200OK
  • 4XXErrors: invalid request, auth, permission, not found, conflict, plan or rate limit
  • 5XXErrors: server or upstream network error
GET/broadcasts
curl "https://api.socialit.com/v1/broadcasts" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
Response · 200
{
  "object": "list",
  "data": [
    {
      "object": "broadcast",
      "id": "string",
      "profile_id": "string",
      "account_id": "string",
      "account_name": "string",
      "platform": "string",
      "name": "string",
      "description": "string",
      "status": "draft",
      "message": {
        "text": "string",
        "attachments": [
          {
            "type": null,
            "url": null,
            "filename": null
          }
        ],
        "message_tag": "string"
      },
      "segment_filters": {
        "tags": [
          "string"
        ],
        "tags_match": "string",
        "exclude_tags": [
          "string"
        ],
        "is_subscribed": true,
        "custom_fields": {}
      },
      "message_preview": "string",
      "rate_limit_per_minute": 1,
      "scheduled_at": "2026-10-13T09:00:00.000Z",
      "started_at": "2026-10-13T09:00:00.000Z",
      "completed_at": "2026-10-13T09:00:00.000Z",
      "recipient_count": 1,
      "pending_count": 1,
      "sent_count": 1,
      "delivered_count": 1,
      "read_count": 1,
      "failed_count": 1,
      "skipped_count": 1,
      "last_error": "string",
      "created_at": "2026-10-13T09:00:00.000Z",
      "updated_at": "2026-10-13T09:00:00.000Z"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}

Create a broadcast draft

POST/broadcasts

segment_filters select recipients by tags, subscription and custom fields.

Access: writeIdempotency-KeyZernio: POST /v1/broadcasts

Try it with MCPAsk your agent to call create-broadcast (toolset broadcasts)Set up MCP

Headers

Idempotency-Keystring

Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

≤ 255 characters

Body object

profile_idstring
account_idstringrequired
platformstring

instagramfacebookxblueskyredditdiscordmastodontiktoktwitter

namestringrequired

1–200 characters

descriptionstring | null

≤ 2000 characters

messageobject
Show 3 child attributes
textstring | null

≤ 4096 characters

attachmentsarray of object

≤ 10 items

Show 3 item attributes
typestring

imagevideoaudiofile

urlstringrequired

1–2048 characters

filenamestring

≤ 255 characters

message_tagstring | null

HUMAN_AGENTCONFIRMED_EVENT_UPDATEPOST_PURCHASE_UPDATEACCOUNT_UPDATE

segment_filtersobject | null
Show 5 child attributes
tagsarray of string

≤ 100 items

tags_matchstring

anyall

exclude_tagsarray of string

≤ 100 items

is_subscribedboolean
custom_fieldsobject
rate_limit_per_minuteinteger | null

1–6000

Returns object

objectstring

broadcast

idstring
profile_idstring | null
account_idstring | null
account_namestring | null
platformstring
namestring
descriptionstring | null
statusstring

draftscheduledsendingcompletedfailedcancelled

messageobject
Show 3 child attributes
textstring | null
attachmentsarray of object
Show 3 item attributes
typestring
urlstring
filenamestring | null
message_tagstring | null
segment_filtersobject | null
Show 5 child attributes
tagsarray of string
tags_matchstring
exclude_tagsarray of string
is_subscribedboolean
custom_fieldsobject
message_previewstring | null
rate_limit_per_minuteinteger | null
scheduled_atstring (date-time) | null
started_atstring (date-time) | null
completed_atstring (date-time) | null
recipient_countinteger
pending_countinteger
sent_countinteger
delivered_countinteger
read_countinteger
failed_countinteger
skipped_countinteger
last_errorstring | null
created_atstring (date-time) | null
updated_atstring (date-time) | null

Responses

  • 201Created
  • 4XXErrors: invalid request, auth, permission, not found, conflict, plan or rate limit
  • 5XXErrors: server or upstream network error
POST/broadcasts
curl -X POST "https://api.socialit.com/v1/broadcasts" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "string",
    "account_id": "string",
    "platform": "instagram",
    "name": "string",
    "description": "string"
  }'
Response · 201
{
  "object": "broadcast",
  "id": "string",
  "profile_id": "string",
  "account_id": "string",
  "account_name": "string",
  "platform": "string",
  "name": "string",
  "description": "string",
  "status": "draft",
  "message": {
    "text": "string",
    "attachments": [
      {
        "type": "string",
        "url": "https://example.com",
        "filename": "string"
      }
    ],
    "message_tag": "string"
  },
  "segment_filters": {
    "tags": [
      "string"
    ],
    "tags_match": "string",
    "exclude_tags": [
      "string"
    ],
    "is_subscribed": true,
    "custom_fields": {}
  },
  "message_preview": "string",
  "rate_limit_per_minute": 1,
  "scheduled_at": "2026-10-13T09:00:00.000Z",
  "started_at": "2026-10-13T09:00:00.000Z",
  "completed_at": "2026-10-13T09:00:00.000Z",
  "recipient_count": 1,
  "pending_count": 1,
  "sent_count": 1,
  "delivered_count": 1,
  "read_count": 1,
  "failed_count": 1,
  "skipped_count": 1,
  "last_error": "string",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z"
}

Preview a broadcast audience

POST/broadcasts/audience-preview

Count (and sample) the contacts a segment reaches on an account.

Access: read

Try it with MCPAsk your agent to call preview-broadcast-audience (toolset broadcasts)Set up MCP

Body object

profile_idstring
account_idstringrequired
segment_filtersobject | null
Show 5 child attributes
tagsarray of string

≤ 100 items

tags_matchstring

anyall

exclude_tagsarray of string

≤ 100 items

is_subscribedboolean
custom_fieldsobject

Returns object

objectstring

audience_preview

countinteger
samplearray of object
Show 3 item attributes
contact_idstring
namestring
platform_identifierstring

Responses

  • 200OK
  • 4XXErrors: invalid request, auth, permission, not found, conflict, plan or rate limit
  • 5XXErrors: server or upstream network error
POST/broadcasts/audience-preview
curl -X POST "https://api.socialit.com/v1/broadcasts/audience-preview" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "string",
    "account_id": "string",
    "segment_filters": {
      "tags": [
        "string"
      ],
      "tags_match": "any"
    }
  }'
Response · 200
{
  "object": "audience_preview",
  "count": 1,
  "sample": [
    {
      "contact_id": "string",
      "name": "string",
      "platform_identifier": "string"
    }
  ]
}

Get a broadcast

GET/broadcasts/{id}

Access: readZernio: GET /v1/broadcasts/{broadcastId}

Try it with MCPAsk your agent to call get-broadcast (toolset broadcasts)Set up MCP

Path parameters

idstringrequired

broadcast id (brd_…)

1–80 characters

Returns object

objectstring

broadcast

idstring
profile_idstring | null
account_idstring | null
account_namestring | null
platformstring
namestring
descriptionstring | null
statusstring

draftscheduledsendingcompletedfailedcancelled

messageobject
Show 3 child attributes
textstring | null
attachmentsarray of object
Show 3 item attributes
typestring
urlstring
filenamestring | null
message_tagstring | null
segment_filtersobject | null
Show 5 child attributes
tagsarray of string
tags_matchstring
exclude_tagsarray of string
is_subscribedboolean
custom_fieldsobject
message_previewstring | null
rate_limit_per_minuteinteger | null
scheduled_atstring (date-time) | null
started_atstring (date-time) | null
completed_atstring (date-time) | null
recipient_countinteger
pending_countinteger
sent_countinteger
delivered_countinteger
read_countinteger
failed_countinteger
skipped_countinteger
last_errorstring | null
created_atstring (date-time) | null
updated_atstring (date-time) | null

Responses

  • 200OK
  • 4XXErrors: invalid request, auth, permission, not found, conflict, plan or rate limit
  • 5XXErrors: server or upstream network error
GET/broadcasts/{id}
curl "https://api.socialit.com/v1/broadcasts/brd_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
Response · 200
{
  "object": "broadcast",
  "id": "string",
  "profile_id": "string",
  "account_id": "string",
  "account_name": "string",
  "platform": "string",
  "name": "string",
  "description": "string",
  "status": "draft",
  "message": {
    "text": "string",
    "attachments": [
      {
        "type": "string",
        "url": "https://example.com",
        "filename": "string"
      }
    ],
    "message_tag": "string"
  },
  "segment_filters": {
    "tags": [
      "string"
    ],
    "tags_match": "string",
    "exclude_tags": [
      "string"
    ],
    "is_subscribed": true,
    "custom_fields": {}
  },
  "message_preview": "string",
  "rate_limit_per_minute": 1,
  "scheduled_at": "2026-10-13T09:00:00.000Z",
  "started_at": "2026-10-13T09:00:00.000Z",
  "completed_at": "2026-10-13T09:00:00.000Z",
  "recipient_count": 1,
  "pending_count": 1,
  "sent_count": 1,
  "delivered_count": 1,
  "read_count": 1,
  "failed_count": 1,
  "skipped_count": 1,
  "last_error": "string",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z"
}

Update a broadcast

PATCH/broadcasts/{id}

Only while draft or scheduled (409 broadcast_not_editable).

Access: writeZernio: PATCH /v1/broadcasts/{broadcastId}

Try it with MCPAsk your agent to call update-broadcast (toolset broadcasts)Set up MCP

Path parameters

idstringrequired

broadcast id (brd_…)

1–80 characters

Body object

namestring

1–200 characters

descriptionstring | null

≤ 2000 characters

messageobject
Show 3 child attributes
textstring | null

≤ 4096 characters

attachmentsarray of object

≤ 10 items

Show 3 item attributes
typestring

imagevideoaudiofile

urlstringrequired

1–2048 characters

filenamestring

≤ 255 characters

message_tagstring | null

HUMAN_AGENTCONFIRMED_EVENT_UPDATEPOST_PURCHASE_UPDATEACCOUNT_UPDATE

segment_filtersobject | null
Show 5 child attributes
tagsarray of string

≤ 100 items

tags_matchstring

anyall

exclude_tagsarray of string

≤ 100 items

is_subscribedboolean
custom_fieldsobject
rate_limit_per_minuteinteger | null

1–6000

Returns object

objectstring

broadcast

idstring
profile_idstring | null
account_idstring | null
account_namestring | null
platformstring
namestring
descriptionstring | null
statusstring

draftscheduledsendingcompletedfailedcancelled

messageobject
Show 3 child attributes
textstring | null
attachmentsarray of object
Show 3 item attributes
typestring
urlstring
filenamestring | null
message_tagstring | null
segment_filtersobject | null
Show 5 child attributes
tagsarray of string
tags_matchstring
exclude_tagsarray of string
is_subscribedboolean
custom_fieldsobject
message_previewstring | null
rate_limit_per_minuteinteger | null
scheduled_atstring (date-time) | null
started_atstring (date-time) | null
completed_atstring (date-time) | null
recipient_countinteger
pending_countinteger
sent_countinteger
delivered_countinteger
read_countinteger
failed_countinteger
skipped_countinteger
last_errorstring | null
created_atstring (date-time) | null
updated_atstring (date-time) | null

Responses

  • 200OK
  • 4XXErrors: invalid request, auth, permission, not found, conflict, plan or rate limit
  • 5XXErrors: server or upstream network error
PATCH/broadcasts/{id}
curl -X PATCH "https://api.socialit.com/v1/broadcasts/brd_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "description": "string",
    "message": {
      "text": "string",
      "attachments": [
        {
          "type": "image",
          "url": "https://example.com"
        }
      ]
    },
    "segment_filters": {
      "tags": [
        "string"
      ],
      "tags_match": "any"
    },
    "rate_limit_per_minute": 1
  }'
Response · 200
{
  "object": "broadcast",
  "id": "string",
  "profile_id": "string",
  "account_id": "string",
  "account_name": "string",
  "platform": "string",
  "name": "string",
  "description": "string",
  "status": "draft",
  "message": {
    "text": "string",
    "attachments": [
      {
        "type": "string",
        "url": "https://example.com",
        "filename": "string"
      }
    ],
    "message_tag": "string"
  },
  "segment_filters": {
    "tags": [
      "string"
    ],
    "tags_match": "string",
    "exclude_tags": [
      "string"
    ],
    "is_subscribed": true,
    "custom_fields": {}
  },
  "message_preview": "string",
  "rate_limit_per_minute": 1,
  "scheduled_at": "2026-10-13T09:00:00.000Z",
  "started_at": "2026-10-13T09:00:00.000Z",
  "completed_at": "2026-10-13T09:00:00.000Z",
  "recipient_count": 1,
  "pending_count": 1,
  "sent_count": 1,
  "delivered_count": 1,
  "read_count": 1,
  "failed_count": 1,
  "skipped_count": 1,
  "last_error": "string",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z"
}

Delete a broadcast

DELETE/broadcasts/{id}

Not while sending (cancel first).

Access: writeZernio: DELETE /v1/broadcasts/{broadcastId}

Try it with MCPAsk your agent to call delete-broadcast (toolset broadcasts)Set up MCP

Path parameters

idstringrequired

broadcast id (brd_…)

1–80 characters

Returns object

objectstringrequired

broadcast

idstringrequired
deletedbooleanrequired

Responses

  • 200OK
  • 4XXErrors: invalid request, auth, permission, not found, conflict, plan or rate limit
  • 5XXErrors: server or upstream network error
DELETE/broadcasts/{id}
curl -X DELETE "https://api.socialit.com/v1/broadcasts/brd_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
Response · 200
{
  "object": "broadcast",
  "id": "string",
  "deleted": true
}

Send a broadcast now

POST/broadcasts/{id}/send

Resolves the segment when no recipients were added (422 no_recipients when nothing matches) and starts sending in rate-limited batches.

Access: writeIdempotency-KeyZernio: POST /v1/broadcasts/{broadcastId}/send

Try it with MCPAsk your agent to call send-broadcast (toolset broadcasts)Set up MCP

Path parameters

idstringrequired

broadcast id (brd_…)

1–80 characters

Headers

Idempotency-Keystring

Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

≤ 255 characters

Returns object

objectstring

broadcast

idstring
profile_idstring | null
account_idstring | null
account_namestring | null
platformstring
namestring
descriptionstring | null
statusstring

draftscheduledsendingcompletedfailedcancelled

messageobject
Show 3 child attributes
textstring | null
attachmentsarray of object
Show 3 item attributes
typestring
urlstring
filenamestring | null
message_tagstring | null
segment_filtersobject | null
Show 5 child attributes
tagsarray of string
tags_matchstring
exclude_tagsarray of string
is_subscribedboolean
custom_fieldsobject
message_previewstring | null
rate_limit_per_minuteinteger | null
scheduled_atstring (date-time) | null
started_atstring (date-time) | null
completed_atstring (date-time) | null
recipient_countinteger
pending_countinteger
sent_countinteger
delivered_countinteger
read_countinteger
failed_countinteger
skipped_countinteger
last_errorstring | null
created_atstring (date-time) | null
updated_atstring (date-time) | null

Responses

  • 200OK
  • 4XXErrors: invalid request, auth, permission, not found, conflict, plan or rate limit
  • 5XXErrors: server or upstream network error
POST/broadcasts/{id}/send
curl -X POST "https://api.socialit.com/v1/broadcasts/brd_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/send" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
Response · 200
{
  "object": "broadcast",
  "id": "string",
  "profile_id": "string",
  "account_id": "string",
  "account_name": "string",
  "platform": "string",
  "name": "string",
  "description": "string",
  "status": "draft",
  "message": {
    "text": "string",
    "attachments": [
      {
        "type": "string",
        "url": "https://example.com",
        "filename": "string"
      }
    ],
    "message_tag": "string"
  },
  "segment_filters": {
    "tags": [
      "string"
    ],
    "tags_match": "string",
    "exclude_tags": [
      "string"
    ],
    "is_subscribed": true,
    "custom_fields": {}
  },
  "message_preview": "string",
  "rate_limit_per_minute": 1,
  "scheduled_at": "2026-10-13T09:00:00.000Z",
  "started_at": "2026-10-13T09:00:00.000Z",
  "completed_at": "2026-10-13T09:00:00.000Z",
  "recipient_count": 1,
  "pending_count": 1,
  "sent_count": 1,
  "delivered_count": 1,
  "read_count": 1,
  "failed_count": 1,
  "skipped_count": 1,
  "last_error": "string",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z"
}

Schedule a broadcast

POST/broadcasts/{id}/schedule

Access: writeIdempotency-KeyZernio: POST /v1/broadcasts/{broadcastId}/schedule

Try it with MCPAsk your agent to call schedule-broadcast (toolset broadcasts)Set up MCP

Path parameters

idstringrequired

broadcast id (brd_…)

1–80 characters

Headers

Idempotency-Keystring

Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

≤ 255 characters

Body object

scheduled_atstring (date-time)required

Returns object

objectstring

broadcast

idstring
profile_idstring | null
account_idstring | null
account_namestring | null
platformstring
namestring
descriptionstring | null
statusstring

draftscheduledsendingcompletedfailedcancelled

messageobject
Show 3 child attributes
textstring | null
attachmentsarray of object
Show 3 item attributes
typestring
urlstring
filenamestring | null
message_tagstring | null
segment_filtersobject | null
Show 5 child attributes
tagsarray of string
tags_matchstring
exclude_tagsarray of string
is_subscribedboolean
custom_fieldsobject
message_previewstring | null
rate_limit_per_minuteinteger | null
scheduled_atstring (date-time) | null
started_atstring (date-time) | null
completed_atstring (date-time) | null
recipient_countinteger
pending_countinteger
sent_countinteger
delivered_countinteger
read_countinteger
failed_countinteger
skipped_countinteger
last_errorstring | null
created_atstring (date-time) | null
updated_atstring (date-time) | null

Responses

  • 200OK
  • 4XXErrors: invalid request, auth, permission, not found, conflict, plan or rate limit
  • 5XXErrors: server or upstream network error
POST/broadcasts/{id}/schedule
curl -X POST "https://api.socialit.com/v1/broadcasts/brd_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/schedule" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduled_at": "2026-10-13T09:00:00.000Z"
  }'
Response · 200
{
  "object": "broadcast",
  "id": "string",
  "profile_id": "string",
  "account_id": "string",
  "account_name": "string",
  "platform": "string",
  "name": "string",
  "description": "string",
  "status": "draft",
  "message": {
    "text": "string",
    "attachments": [
      {
        "type": "string",
        "url": "https://example.com",
        "filename": "string"
      }
    ],
    "message_tag": "string"
  },
  "segment_filters": {
    "tags": [
      "string"
    ],
    "tags_match": "string",
    "exclude_tags": [
      "string"
    ],
    "is_subscribed": true,
    "custom_fields": {}
  },
  "message_preview": "string",
  "rate_limit_per_minute": 1,
  "scheduled_at": "2026-10-13T09:00:00.000Z",
  "started_at": "2026-10-13T09:00:00.000Z",
  "completed_at": "2026-10-13T09:00:00.000Z",
  "recipient_count": 1,
  "pending_count": 1,
  "sent_count": 1,
  "delivered_count": 1,
  "read_count": 1,
  "failed_count": 1,
  "skipped_count": 1,
  "last_error": "string",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z"
}

Cancel a broadcast

POST/broadcasts/{id}/cancel

Pending recipients become skipped.

Access: writeZernio: POST /v1/broadcasts/{broadcastId}/cancel

Try it with MCPAsk your agent to call cancel-broadcast (toolset broadcasts)Set up MCP

Path parameters

idstringrequired

broadcast id (brd_…)

1–80 characters

Returns object

objectstring

broadcast

idstring
profile_idstring | null
account_idstring | null
account_namestring | null
platformstring
namestring
descriptionstring | null
statusstring

draftscheduledsendingcompletedfailedcancelled

messageobject
Show 3 child attributes
textstring | null
attachmentsarray of object
Show 3 item attributes
typestring
urlstring
filenamestring | null
message_tagstring | null
segment_filtersobject | null
Show 5 child attributes
tagsarray of string
tags_matchstring
exclude_tagsarray of string
is_subscribedboolean
custom_fieldsobject
message_previewstring | null
rate_limit_per_minuteinteger | null
scheduled_atstring (date-time) | null
started_atstring (date-time) | null
completed_atstring (date-time) | null
recipient_countinteger
pending_countinteger
sent_countinteger
delivered_countinteger
read_countinteger
failed_countinteger
skipped_countinteger
last_errorstring | null
created_atstring (date-time) | null
updated_atstring (date-time) | null

Responses

  • 200OK
  • 4XXErrors: invalid request, auth, permission, not found, conflict, plan or rate limit
  • 5XXErrors: server or upstream network error
POST/broadcasts/{id}/cancel
curl -X POST "https://api.socialit.com/v1/broadcasts/brd_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/cancel" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
Response · 200
{
  "object": "broadcast",
  "id": "string",
  "profile_id": "string",
  "account_id": "string",
  "account_name": "string",
  "platform": "string",
  "name": "string",
  "description": "string",
  "status": "draft",
  "message": {
    "text": "string",
    "attachments": [
      {
        "type": "string",
        "url": "https://example.com",
        "filename": "string"
      }
    ],
    "message_tag": "string"
  },
  "segment_filters": {
    "tags": [
      "string"
    ],
    "tags_match": "string",
    "exclude_tags": [
      "string"
    ],
    "is_subscribed": true,
    "custom_fields": {}
  },
  "message_preview": "string",
  "rate_limit_per_minute": 1,
  "scheduled_at": "2026-10-13T09:00:00.000Z",
  "started_at": "2026-10-13T09:00:00.000Z",
  "completed_at": "2026-10-13T09:00:00.000Z",
  "recipient_count": 1,
  "pending_count": 1,
  "sent_count": 1,
  "delivered_count": 1,
  "read_count": 1,
  "failed_count": 1,
  "skipped_count": 1,
  "last_error": "string",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z"
}

List broadcast recipients

GET/broadcasts/{id}/recipients

Access: readZernio: GET /v1/broadcasts/{broadcastId}/recipients

Try it with MCPAsk your agent to call list-broadcast-recipients (toolset broadcasts)Set up MCP

Path parameters

idstringrequired

broadcast id (brd_…)

1–80 characters

Query parameters

pageintegerdefault: 1

Page number

≥ 1

limitintegerdefault: 20

Items per page (max 100)

1–100

sortstring

created_atsent_at

orderstring

ascdesc

matchstring

Combine filters with AND (default) or OR

allor

statusstring
contact_idstring

Returns object

objectstringrequired

list

dataarray of objectrequired
Show 15 item attributes
objectstring

broadcast_recipient

idstring
broadcast_idstring
contact_idstring | null
channel_idstring | null
contact_namestring | null
platform_identifierstring | null
statusstring

pendingsentdeliveredreadfailedskipped

message_idstring | null
errorstring | null
error_codestring | null
sent_atstring (date-time) | null
delivered_atstring (date-time) | null
read_atstring (date-time) | null
created_atstring (date-time) | null
pageintegerrequired
limitintegerrequired
totalinteger | null
has_morebooleanrequired
next_page_urlstring | null
previous_page_urlstring | null

Responses

  • 200OK
  • 4XXErrors: invalid request, auth, permission, not found, conflict, plan or rate limit
  • 5XXErrors: server or upstream network error
GET/broadcasts/{id}/recipients
curl "https://api.socialit.com/v1/broadcasts/brd_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/recipients" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
Response · 200
{
  "object": "list",
  "data": [
    {
      "object": "broadcast_recipient",
      "id": "string",
      "broadcast_id": "string",
      "contact_id": "string",
      "channel_id": "string",
      "contact_name": "string",
      "platform_identifier": "string",
      "status": "pending",
      "message_id": "string",
      "error": "string",
      "error_code": "string",
      "sent_at": "2026-10-13T09:00:00.000Z",
      "delivered_at": "2026-10-13T09:00:00.000Z",
      "read_at": "2026-10-13T09:00:00.000Z",
      "created_at": "2026-10-13T09:00:00.000Z"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}

Add broadcast recipients

POST/broadcasts/{id}/recipients

By contact_ids and/or use_segment. Contacts without a subscribed channel on the account are skipped.

Access: writeIdempotency-KeyZernio: POST /v1/broadcasts/{broadcastId}/recipients

Try it with MCPAsk your agent to call add-broadcast-recipients (toolset broadcasts)Set up MCP

Path parameters

idstringrequired

broadcast id (brd_…)

1–80 characters

Headers

Idempotency-Keystring

Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

≤ 255 characters

Body object

contact_idsarray of string

≤ 10000 items

use_segmentboolean

Returns object

objectstring

broadcast_recipients_result

addedinteger
skippedinteger
recipient_countinteger

Responses

  • 200OK
  • 4XXErrors: invalid request, auth, permission, not found, conflict, plan or rate limit
  • 5XXErrors: server or upstream network error
POST/broadcasts/{id}/recipients
curl -X POST "https://api.socialit.com/v1/broadcasts/brd_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/recipients" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_ids": [
      "string"
    ],
    "use_segment": true
  }'
Response · 200
{
  "object": "broadcast_recipients_result",
  "added": 1,
  "skipped": 1,
  "recipient_count": 1
}