canonical: https://jentic.com/apis/captivated.works/captivated-works

# Captivated Works Captivated Messaging API

Jentic publishes the only available OpenAPI specification for Captivated Messaging API, keeping it validated and agent-ready. The Captivated Messaging API sends individual and bulk SMS or MMS messages with support for scheduled delivery, image and file attachments, and asynchronous job tracking for large sends. It also provides phone number lookups so senders can validate destination numbers before dispatch. Customer engagement teams use it to drive marketing blasts, transactional alerts, and conversational replies from existing CRM and ticketing tools.

## For AI agents

Send SMS or MMS messages individually or in bulk, schedule delivery, attach files, and track bulk send jobs. Includes a phone number lookup endpoint for pre-send validation.

## Scope

Does not handle voice calls, email delivery, or in-app push - use for SMS, MMS, bulk messaging, and phone number lookups only.

## Capabilities

- Send a single SMS or MMS to a recipient with optional attachments
- Submit a bulk message job to deliver to many recipients in a single request
- Schedule a message for future delivery and retrieve its status by message id
- Poll a bulk send job to track delivery progress and per-recipient outcomes
- Look up a phone number to validate format and reachability before sending

## Use cases

### Transactional SMS Alerts

Operational systems send order updates, appointment reminders, and verification codes via POST /api/command/v1/messages. The endpoint accepts a single recipient with optional attachments and returns a message id that can be polled at GET /api/command/v1/messages/{message_id} to confirm delivery. Volume is moderate and latency-sensitive.

Example prompt: POST /api/command/v1/messages with the recipient phone number and the alert text, then poll GET /api/command/v1/messages/{message_id} to confirm delivery.

### Bulk Marketing Send

Marketing campaigns blast a promotion to a segmented contact list. POST /api/command/v1/messages/bulk_create accepts the list of recipients in a single call and returns a job id. The team polls GET /api/command/v1/jobs/{job_id} for progress and per-recipient status, treating the call as fire-and-forget once submission succeeds.

Example prompt: POST /api/command/v1/messages/bulk_create with the array of recipients and the message body, then poll GET /api/command/v1/jobs/{job_id} until completion.

### Phone Number Validation Pipeline

Before adding a number to a contact list or sending a costly MMS, GET /api/command/v1/phone_number_lookups/{phone_number} validates the number's format and reachability. The lookup result feeds a CRM data quality rule and prevents wasted sends to unreachable numbers.

Example prompt: GET /api/command/v1/phone_number_lookups/+15551234567 and write the lookup result against the contact record in the CRM.

### AI Agent Outbound Messaging

An agent that triages support follow-ups uses Captivated via Jentic to send a personalised SMS once a ticket closes. It searches for the send-message operation, loads the schema, and submits the SMS - credentials stay encrypted in your Jentic One instance throughout.

Example prompt: Search Jentic for 'send a Captivated SMS', load the createMessage schema, and execute POST /api/command/v1/messages with the recipient and body.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /api/command/v1/messages | Send a single SMS or MMS |
| POST | /api/command/v1/messages/bulk_create | Submit a bulk message job |
| GET | /api/command/v1/messages/{message_id} | Get delivery status of a message |
| GET | /api/command/v1/jobs/{job_id} | Track a bulk send job |
| GET | /api/command/v1/phone_number_lookups/{phone_number} | Validate a phone number |

## Key resources

- **Messages** — Send single messages, retrieve message status, and submit bulk message jobs
- **Jobs** — Poll bulk message job status and per-recipient outcomes
- **Phone Number Lookups** — Validate a phone number's format and reachability before sending

## Why Jentic

- **Setup:** Wiring the Captivated Messaging API by hand means minting a bearer token from your profile credentials, attaching it to the Authorization header on every request, and tracking bulk-send jobs against the api.captivated.works host yourself. Through Jentic you install once, import the Captivated Messaging API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Captivated takes the recipient in the request body rather than the URL path, so you scope by operation: limit the agent to the operations it needs, such as sending a single message or looking up a phone number, and leave bulk creation out of the allowed set until you want it.
- **Credential handling:** Your Captivated bearer token is stored once, encrypted, by your own Jentic One instance and injected into the Authorization header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'send an SMS' or 'submit a bulk SMS job', and Jentic returns the matching Captivated operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Captivated (alternate slug)** — Alternate slug for the same Captivated platform in the catalog
- **Canny API** — Capture customer feedback that triggers a Captivated SMS follow-up
- **Cantrip API** — Publish CMS content and route follow-up messages via Captivated

## FAQ

### Why is there no official OpenAPI spec for Captivated Messaging API?

Captivated does not publish an OpenAPI specification on its developer site. Jentic generates and maintains this spec so that AI agents and developers can call Captivated Messaging API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Captivated Messaging API use?

Captivated uses bearer token authentication, with the token obtained from the user profile under Password and Credentials. Through Jentic the bearer token is stored encrypted in the vault and never appears in the agent's prompt context.

### Can I send a bulk SMS to thousands of recipients with the Captivated API?

Yes. POST /api/command/v1/messages/bulk_create accepts an array of recipients in one request and returns a job id. Poll GET /api/command/v1/jobs/{job_id} for the per-recipient delivery status.

### How do I send a scheduled SMS through Jentic?

Search Jentic for 'send a Captivated SMS', load the createMessage operation, and execute POST /api/command/v1/messages with the recipient, body, and a scheduled_at timestamp in the request payload.

### What are the rate limits for the Captivated Messaging API?

Captivated does not publish rate limits in the OpenAPI spec. Bulk sends are queued asynchronously, so prefer bulk_create over many single calls and back off on 429 responses.

### Can I attach an image to a Captivated message?

Yes. The createMessage payload supports attachments, sending it as MMS instead of plain SMS. Confirm the recipient carrier supports MMS via GET /api/command/v1/phone_number_lookups/{phone_number} before sending costly MMS at scale.

### Can I limit what my agent is allowed to do with the Captivated Messaging API?

Yes. Because you run Jentic One yourself, your own rules decide which Captivated operations and credentials the agent may use. Since Captivated takes the recipient in the request body rather than the URL path, you scope by operation: allow only the calls the agent needs, such as sending a single message via POST /api/command/v1/messages or validating a number via GET /api/command/v1/phone_number_lookups/{phone_number}. You can leave bulk creation via POST /api/command/v1/messages/bulk_create out of the allowed set until you decide to permit it.