Choose your integration workflow

Start with a simulated request

Complete workspace setup, create a test key, and follow the quickstart. Test and live requests use https://usebuddy.app/api/v1; your credential selects the mode. Use the API reference for each operation's required scopes, request fields and responses.

Payment and account notifications

Use POST /messages for one notification to one recipient. Choose an approved utility template and its exact language, provide its variables, and use transactional: true when the recipient is not a subscriber. This flag does not override a STOP. Keep the recipient's permission and the purpose of the message clear.

Persist a unique idempotency key with your business event before sending, such as a payment receipt ID. Store the returned data.id. Follow message webhooks or GET /messages/{id} to learn delivery status. A delivery receipt does not prove that a payment succeeded; use your payment system as the authority.

Requested authentication codes

Use POST /otp after the person requests a code, then POST /otp/verify to check it. Keep the challenge ID on your server. Follow the OTP guide for expiry, attempt limits and resend rules; handle invalid, expired and exhausted challenges separately. Test mode supplies a test_code for integration checks.

Subscribers and campaign announcements

Create a subscriber only after collecting consent. Store your customer identifier in external_id and record the consent evidence. Use tags to group recipients and inspect consent history when needed. POST /subscribers/{id}/opt_out records a withdrawal; deleting a subscriber is a separate erasure action.

Create a campaign draft with one audience selector: all subscribers, tags, or a segment. Supply the template, language and any required header or button parameters. Send the draft with POST /campaigns/{id}/send and a JSON body of {}, or schedule it with send_at. Both require an idempotency key. Follow campaign results and recipient statuses rather than treating acceptance as completion.

Event-driven journeys

Use POST /events with an event name, stable producer ID, properties and exactly one subject: phone, subscriber or external_id. Configure the matching automation in Buddy. Test events let you inspect matches without executing a live automation. Event ingestion and outbound webhooks are separate directions: you send business events to Buddy; Buddy sends status events to your receiver.

Connect customer workspaces

For a platform serving multiple businesses, use OAuth so each workspace owner grants access to their own workspace. Request mode=test during development. Store each workspace's authorization separately and stop work when it is revoked. Follow the OAuth guide for PKCE, state validation and refresh-token rotation.

Show a component inside your application

Create an embedded session from your server using POST /embedded_sessions. Supported components are message_status, campaign_results and template_picker. The first two require a resource ID. Set the exact host origin and a short expiry (60–900 seconds, default 300). Keep the parent API key on your server. The returned client secret is restricted to that component and expires with the session.