REST API v1

BEAM API Documentation

Send Personalized Messages Through Multiple Channels

Integrate BEAM into your platform and send beautiful personalized messages via email, text, QR codes, AR experiences, and more. Our RESTful API makes it simple.

1

Get API Key

Create your API key from the dashboard to authenticate requests

2

Make Request

Send POST request with recipient info and message content

✓

Get Beam URL

Receive shareable link to beautifully rendered beam

🔑

Authentication

To use the BEAM API, you'll need to create an API key from your dashboard. All API requests must include your API key in the Authorization header.

Authorization: Bearer YOUR_API_KEY
🌐

Base URL

https://www.beam-us.com/api/v1
⚡

Rate Limits

100 requests/hour per API key

Need higher limits? Contact us for enterprise plans.

📮

Create a Beam

POST /api/v1/beams

→Request Body

{ "recipientName": "John Doe", "senderName": "Jane Smith", "message": "Happy Birthday!", "beamType": "postcard", "theme": "birthday", "image": "data:image/png;base64,..." // or image URL }

←Response

{ "success": true, "beam": { "id": "abc123", "url": "https://www.beam-us.com/gram/abc123", "recipientName": "John Doe", "senderName": "Jane Smith", "beamType": "postcard", "createdAt": "2025-12-19T12:00:00Z" } }
cURL
curl -X POST https://www.beam-us.com/api/v1/beams \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "recipientName": "John Doe", "senderName": "Jane Smith", "message": "Happy Birthday!", "beamType": "postcard", "theme": "birthday" }'
JavaScript
const response = await fetch('https://www.beam-us.com/api/v1/beams', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ recipientName: 'John Doe', senderName: 'Jane Smith', message: 'Happy Birthday!', beamType: 'postcard', theme: 'birthday' }) }); const data = await response.json(); console.log(data.beam.url);
Python
import requests response = requests.post( 'https://www.beam-us.com/api/v1/beams', headers={ 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, json={ 'recipientName': 'John Doe', 'senderName': 'Jane Smith', 'message': 'Happy Birthday!', 'beamType': 'postcard', 'theme': 'birthday' } ) data = response.json() print(data['beam']['url'])
📋

Get Your Beams

GET /api/v1/beams

Query Parameters

  • limitNumber of beams to return (default: 10)
  • offsetPagination offset (default: 0)
curl -X GET "https://www.beam-us.com/api/v1/beams?limit=20&offset=0" \ -H "Authorization: Bearer YOUR_API_KEY"
🔍

Get a Specific Beam

GET /api/v1/beams/:id
curl -X GET "https://www.beam-us.com/api/v1/beams/abc123" \ -H "Authorization: Bearer YOUR_API_KEY"

Beam Types

messageText-only beam
postcardBeam with custom image
ai-imageBeam with AI-generated image
qr-codeBeam with QR code
emailBeam sent via email
textBeam sent via text message

Themes

defaultStandard theme
birthdayBirthday celebration
holidayHoliday/Christmas
new-yearNew Year's celebration
celebrationGeneral celebration
milestoneAchievement/milestone
❌

Error Handling

The API returns standard HTTP status codes. All error responses include a JSON body with an error message.

400Bad Request

Invalid request parameters or missing required fields

401Unauthorized

Invalid or missing API key

429Too Many Requests

Rate limit exceeded

500Internal Server Error

Server error - please retry or contact support

🎯

Use Cases

📲 Multi-Channel Campaigns

Send personalized messages via email, text, QR codes, or AR - choose the best channel for each recipient

🎂 Automated Birthday Greetings

Send augmented reality birthday greetings from your app

🎄 Holiday Campaigns

Create festive messages with multiple delivery options for your users

🎉 Event Invitations

Send unique invitations with QR codes for easy RSVP

💼 Customer Appreciation

Thank customers with personalized messages they can share

📱 Mobile App Integration

Add BEAM messaging to your iOS, Android, or web application

💡

Best Practices

📲

Choose the Right Channel

Consider your audience - email for formal messages, QR codes for physical spaces, AR for immersive experiences

🔒

Store API Keys Securely

Never expose API keys in client-side code or commit them to version control

⚡

Handle Rate Limits

Implement exponential backoff when you receive 429 responses

🎨

Optimize Images

Compress images before uploading to reduce API response times

📊

Track Beam Performance

Use the API to retrieve beam analytics and see which channels perform best

Need Help?

Have questions about integrating multi-channel messaging into your application? Our team is here to help.