# Blooio API v2

> RESTful API for iMessage automation. Send messages, manage contacts, groups, and webhooks.

## API Reference

- GET /me: Get current authentication context
- GET /me/numbers: List phone numbers
- GET /me/numbers/{number}/contact-card: Get contact card (Coming Soon)
- PUT /me/numbers/{number}/contact-card: Update contact card
- POST /me/numbers/{number}/call-forwarding: Request call forwarding
- GET /contacts: List contacts
- POST /contacts: Create a contact
- GET /contacts/{contactId}: Get a contact
- PATCH /contacts/{contactId}: Update a contact
- DELETE /contacts/{contactId}: Delete a contact
- GET /contacts/{contactId}/capabilities: Check contact capabilities
- GET /contacts/{contactId}/tags: List contact tags
- POST /contacts/{contactId}/tags: Add tags to a contact
- DELETE /contacts/{contactId}/tags/{tag}: Remove a tag from a contact
- GET /location/contacts: List contact locations
- GET /location/contacts/{handle}: Get contact location
- POST /location/contacts/refresh: Refresh contact locations
- POST /facetime/calls: Initiate a FaceTime call (Coming Soon)
- GET /groups: List groups
- POST /groups: Create a group
- GET /groups/{groupId}: Get a group
- PATCH /groups/{groupId}: Update a group
- DELETE /groups/{groupId}: Delete a group
- GET /groups/{groupId}/members: List group members
- POST /groups/{groupId}/members: Add a member to a group (Coming Soon)
- DELETE /groups/{groupId}/members/{contactId}: Remove a member from a group (Coming Soon)
- POST /groups/{groupId}/icon: Set group icon
- DELETE /groups/{groupId}/icon: Remove group icon
- GET /webhooks: List webhooks
- POST /webhooks: Create a webhook (closed)
- GET /webhooks/{webhookId}: Get a webhook
- PATCH /webhooks/{webhookId}: Update a webhook
- DELETE /webhooks/{webhookId}: Delete a webhook
- POST /webhooks/{webhookId}/secret/rotate: Rotate webhook signing secret
- GET /webhooks/{webhookId}/logs: List webhook logs
- POST /webhooks/{webhookId}/logs/{eventId}/replay: Replay a webhook event
- GET /chats: List chats
- GET /chats/{chatId}: Get a chat
- GET /chats/{chatId}/messages: List messages in a chat
- POST /chats/{chatId}/messages: Send a message
- GET /chats/{chatId}/messages/{messageId}: Get a message
- GET /chats/{chatId}/messages/{messageId}/status: Get message status
- POST /chats/{chatId}/messages/{messageId}/reactions: Add or remove a reaction
- POST /chats/{chatId}/polls: Send a poll
- GET /chats/{chatId}/polls/{pollId}: Get poll results
- POST /chats/{chatId}/typing: Start typing indicator
- DELETE /chats/{chatId}/typing: Stop typing indicator
- POST /chats/{chatId}/read: Mark chat as read
- POST /chats/{chatId}/contact-card: Share contact card
- GET /chats/{chatId}/background: Get chat background
- PUT /chats/{chatId}/background: Set chat background
- DELETE /chats/{chatId}/background: Remove chat background
- GET /phone-numbers/lookup: Look up a phone number
- POST /phone-numbers/lookup: Look up a phone number
- POST /phone-numbers/batch: Batch look up phone numbers
- GET /analytics/risk-tolerance: Get risk-tolerance report
- GET /analytics/risk-tolerance/summary: Get risk-tolerance summary
- GET /analytics/risk-tolerance/{number}: Get risk-tolerance report for a number

## Guides

- [iMessage REST API](https://docs.blooio.com/guides/imessage-rest-api): A complete reference to the Blooio iMessage REST API — resources, HTTP verbs, authentication, errors, and idempotency.
- [Message sending basics](https://docs.blooio.com/guides/message-sending): A complete guide to sending messages, including chat IDs, options, and common quirks
- [Messaging safety limits and recovery](https://docs.blooio.com/guides/messaging-safety): Understand conversation limits, number protections, error codes, and the steps that restore sending
- [Message fields reference (v2)](https://docs.blooio.com/guides/message-fields): Every field on a v2 message object, plus the full status lifecycle and protocol (transport) states
- [Message fields reference (v4)](https://docs.blooio.com/guides/message-fields-v4): Every field on a v4 multi-channel message object, plus the full status lifecycle and protocol (transport) states across iMessage, SMS, RCS, and WhatsApp
- [Send iMessage with Python](https://docs.blooio.com/guides/send-imessage-api-python): A hands-on Python tutorial for sending and receiving iMessages via the Blooio REST API — requests, async with httpx, webhooks, and a working FastAPI example.
- [Send iMessage with Node.js](https://docs.blooio.com/guides/send-imessage-api-nodejs): A Node.js (JavaScript and TypeScript) tutorial for sending and receiving iMessages via the Blooio REST API — fetch, async/await, Express webhooks, and bulk patterns.
- [Contact cards (Name & Photo)](https://docs.blooio.com/guides/contact-card): How to manage and share your iMessage contact card — the Name & Photo identity others see in conversations
- [Number Purchase API](https://docs.blooio.com/guides/number-purchase-api): Programmatically browse, buy, and remove Blooio lines over the v4 API — including the KYC, access-approval, and billing steps required before you can purchase.
- [Receive webhooks locally](https://docs.blooio.com/guides/webhooks-local): Tunnel your local server and test Blooio webhook deliveries
- [Verify webhook signatures](https://docs.blooio.com/guides/webhook-signatures): Cryptographically verify that webhooks are genuinely from Blooio
- [Send attachments](https://docs.blooio.com/guides/attachments): Include media URLs when sending messages
- [Rich link previews](https://docs.blooio.com/guides/link-previews): Send URL messages with iMessage-style rich previews, override the image and title, and batch-send multiple links in one request
- [Custom bubbles (iMessage apps)](https://docs.blooio.com/guides/custom-bubbles): Send and receive bring-your-own iMessage app extension bubbles
- [Find My & Check In bubbles](https://docs.blooio.com/guides/apple-system-apps): Send Apple's first-party Find My and Check In iMessage app bubbles
- [Contact flows](https://docs.blooio.com/guides/contact-flows): Check iMessage/SMS capabilities and choose the best channel
- [Error handling & retries](https://docs.blooio.com/guides/error-handling): Handle common errors, rate limits, and implement safe retries
- [Twilio Integration](https://docs.blooio.com/guides/twilio-integration): Send SMS/MMS messages using your own Twilio account
- [WhatsApp Business](https://docs.blooio.com/guides/whatsapp-business): Send and receive WhatsApp messages through the official WhatsApp Business Platform (Cloud API) — templates, the 24-hour customer service window, media, and interactive messages
- [Location tracking (FindMy)](https://docs.blooio.com/guides/location-tracking): How to track the real-time location of contacts who share their location via Apple FindMy
- [FaceTime calls](https://docs.blooio.com/guides/facetime): How to initiate FaceTime calls programmatically and get shareable links
- [Number Pools](https://docs.blooio.com/guides/number-pools): How sender number selection works for Blooio and Twilio messages