The ViralDM REST API

Introduction

The ViralDM API is a REST API that takes and returns JSON. It is the same API the ViralDM mobile app and the MCP server use, so anything you can do there you can do from your own code.

Every path in these docs is relative to the base URL https://viraldm.app/api/v1. Send bodies as Content-Type: application/json.

Authentication

Create a key in Dashboard → API keys. A key looks like vdm_ followed by 48 hex characters. It is shown once, when you create it; ViralDM stores only a hash, so nobody can read it back later. Revoke a key there too.

Send the key in either header:

Your first request

GET /me returns the user and the key making the call. It is the quickest way to check a key works.

curl https://viraldm.app/api/v1/me \
  -H "X-API-Key: $VIRALDM_API_KEY"

// Node 18+ has fetch built in
const res = await fetch('https://viraldm.app/api/v1/me', {
  headers: { 'X-API-Key': process.env.VIRALDM_API_KEY }
});
console.log(await res.json());

import os, requests

r = requests.get('https://viraldm.app/api/v1/me',
                 headers={'X-API-Key': os.environ['VIRALDM_API_KEY']})
print(r.json())

Read and write permissions

A key is read-only unless you give it write permission when you create it. GET requests need read. Every other method (POST, PUT, DELETE) needs write; a read-only key gets 403 with This credential is read-only.

OAuth tokens

AI assistants that connect over MCP get an OAuth 2.0 access token instead of a key. The API accepts it as a Bearer token with the same rules: mcp:read can read, mcp:write can also change things. Setup is on the MCP server page.

Quick start

1. Sign up at viraldm.app. The free first month includes API access.
2. Connect Instagram in the dashboard. It must be a Business or Creator account.
3. Create a key in Dashboard → API keys. Tick write if you will create things.
4. Find your account id with GET /accounts.
5. Create an automation. The example below DMs everyone who comments LINK and replies to their comment in public.

# 1. Your connected accounts
curl https://viraldm.app/api/v1/accounts -H "X-API-Key: $VIRALDM_API_KEY"

# 2. Comment LINK, get a DM
curl -X POST https://viraldm.app/api/v1/automations \
  -H "X-API-Key: $VIRALDM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "LINK on Reels",
    "socialAccountId": "ACCOUNT_ID",
    "type": "COMMENT_TO_DM",
    "trigger": { "keywords": ["link"] },
    "action": {
      "message": "Here is the guide: https://example.com/guide",
      "commentReply": "Sent it to your DMs"
    }
  }'

const api = (path, opts = {}) =>
  fetch('https://viraldm.app/api/v1' + path, {
    ...opts,
    headers: { 'X-API-Key': process.env.VIRALDM_API_KEY, 'Content-Type': 'application/json' }
  }).then(r => r.json());

const { data: accounts } = await api('/accounts');

const created = await api('/automations', {
  method: 'POST',
  body: JSON.stringify({
    name: 'LINK on Reels',
    socialAccountId: accounts[0].id,
    type: 'COMMENT_TO_DM',
    trigger: { keywords: ['link'] },
    action: { message: 'Here is the guide: https://example.com/guide', commentReply: 'Sent it to your DMs' }
  })
});
console.log(created.data.id);

import os, requests

API = 'https://viraldm.app/api/v1'
H = {'X-API-Key': os.environ['VIRALDM_API_KEY']}

accounts = requests.get(API + '/accounts', headers=H).json()['data']

r = requests.post(API + '/automations', headers=H, json={
    'name': 'LINK on Reels',
    'socialAccountId': accounts[0]['id'],
    'type': 'COMMENT_TO_DM',
    'trigger': {'keywords': ['link']},
    'action': {'message': 'Here is the guide: https://example.com/guide',
               'commentReply': 'Sent it to your DMs'}
})
print(r.status_code, r.json())

Limits and quotas

Each request is checked against the allowance on your account: requests per second, calls per month and, on Free Dev, calls per day. An API plan sets its own allowance. An app plan with API access includes the allowance of one API plan, with read and write access: the free first month gets API Starter's, Starter gets API Starter's (through MCP only), Growth gets API Growth's, Agency gets API Scale's and Agency Pro gets API Agency's. Free through MCP gets Free Dev's, reads only.

Calls are counted per account, not per key, and OAuth calls from MCP count too. Months and days are calendar months and days. Some routes have their own ceilings on top:

• 3,000 requests a minute per X-API-Key (per IP address for Bearer tokens), on every plan.
• 200 requests a minute per IP address across /api.
• 10 a minute on the AI generation routes (/ai/…) and 5 a minute on /profile-audit.

Response headers

Over a limit you get 429. The body says which limit: Rate limit exceeded (per second, retry after 1 second), Monthly API quota exceeded or Daily API quota exceeded (free tier), with used and limit. The monthly quota is a hard stop until the next month or a bigger plan.

Errors

Errors come back as JSON with an error message, and often a code, reason or upgradeUrl.

{
  "error": "This credential is read-only.",
  "detail": "POST requires write permission. This key has: read."
}

Automations

An automation listens for a trigger (a comment keyword, a DM keyword, a story reply) and sends a reply. The same plan limits as the dashboard apply: the number of automations and keywords per automation.

Body

Types

Conditions

Set these inside trigger.

Late to set one up? POST /automations/:id/rewind sends it to the last 7 days of commenters. GET on the same path is a dry run that tells you how many people qualify.

Accounts

Connect accounts in the dashboard; the API works with accounts that are already connected. Instagram needs a Business or Creator account.

Sending a DM

Body: socialAccountId, recipientId (the person's Instagram-scoped id) and message. API sends are automated messages, so Meta's rule applies: the person must have messaged you in the last 24 hours. Outside that window you get 409 with Cannot DM this user and a reason.

Subscribers and segments

The response has data, total (the full count, not the page) and limit.

Body: action (add or remove), subscriberIds and tag. A new tag starts any sequence that is triggered by it.

Named audiences with a live count. Pass an id as a broadcast's segment. Each one is worked out from current data, and people who opted out are never in any of them.

Sequences

Drip DMs: a series of messages with delays between them.

{
  "name": "Welcome series",
  "trigger": { "type": "KEYWORD", "keywords": ["welcome", "start"] },
  "steps": [
    { "delayMinutes": 0,    "message": "Hi, welcome in." },
    { "delayMinutes": 60,   "message": "Here is what we do…" },
    { "delayMinutes": 1440, "message": "A day later: any questions?" }
  ]
}

Trigger types are KEYWORD, COMMENT and TAG. A new-follower trigger is refused: Instagram does not send ViralDM a follow event, and you cannot DM someone who has not messaged you. A new sequence runs on your first active account; move it with PUT and socialAccountId.

Broadcasts

Creating a broadcast does not send it. You get the real recipient count back first; DMs go out only when you pass send: true.

{
  "name": "Weekend sale",
  "message": "50% off this weekend only.",
  "segment": "customers",
  "send": false
}

// → { "id": "…", "recipientCount": 212, "status": "DRAFT", "scheduled": false }

People who opted out are left out of the count and the send. Anyone outside the 24-hour messaging window is skipped, not failed.

Scheduled posts

GET /scheduled-posts takes platform (default all) and days ahead (default 7). A post has platform, scheduledFor (ISO), postType (POST, CAROUSEL, REEL or STORY), content and mediaUrl. A carousel takes mediaUrls with 2 to 10 items. PUT works only while the post is still SCHEDULED.

For your own files, POST /media/initiate gives an upload URL and POST /media/:mediaId/finalize returns the public URL. POST /media is a one-shot upload for small images.

Store and orders

Your digital store: files, locked content, courses, memberships, events, 1:1 sessions and external links.

{
  "title": "Instagram Growth Playbook",
  "type": "DIGITAL_FILE",
  "price": 499,
  "comparePrice": 999,
  "gstPercent": 18,
  "stockLimit": 100,
  "deliverUrl": "https://drive.google.com/…",
  "deliverMessage": "Thanks! Your playbook is here."
}

PUT is a partial update: send only what changes. New products start as DRAFT and are not on the web until you set { "status": "PUBLISHED" }. Statuses are DRAFT, PUBLISHED, UNLISTED and ARCHIVED.

Orders

Buyers pay you directly over UPI. ViralDM is never in the money path, so confirming a payment is your call. POST /orders/:id/paid is for a server that has already seen the money arrive, such as your own payment webhook. It delivers the product and books the revenue, and it is idempotent: confirming twice does not deliver twice. It is deliberately not available to AI assistants over MCP.

GET /orders takes status (PENDING, PAID, CANCELLED, REFUNDED) and limit (up to 200). GET /store/stats?days=30 (1 to 365) returns:

{
  "periodDays": 30,
  "summary": {
    "revenuePaise": 1247500, "paidCount": 25, "avgOrderPaise": 49900,
    "conversionPct": 42, "startedCount": 59
  },
  "series":    [ { "date": "2026-08-01", "revenuePaise": 49900, "orders": 1 } ],
  "byProduct": [ { "title": "Growth Playbook", "paidCount": 25, "revenuePaise": 1247500 } ]
}

Revenue counts on the day an order was paid, not the day checkout began. conversionPct is null when no checkout has started, which is not the same as 0%.

AI Calls

Phone a lead from code. An Indian number rings, the AI talks in the lead's language, and the transcript, summary and outcome fill in on the call. POST needs a write key.

curl -X POST https://viraldm.app/api/v1/calls \
  -H "X-API-Key: $VIRALDM_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "phone": "9876543210",
    "name": "Rahul",
    "purpose": "Asked about the Growth plan on Instagram",
    "context": "Runs a travel page",
    "consent": { "source": "call_request", "at": "2026-10-15T10:42:00+05:30", "note": "Asked for a call in DM" },
    "config": { "agentName": "Priya", "voice": "female", "language": "hinglish" }
  }'
# → 201 { "success": true, "immediate": true, "data": { "id": "…", "status": "…" } }

curl https://viraldm.app/api/v1/calls/CALL_ID -H "X-API-Key: $VIRALDM_API_KEY"
# status ends as COMPLETED, NO_ANSWER or FAILED; transcript, summary, outcome fill in

phone is a 10-digit Indian mobile number. config is optional, per call: agentName, voice (female or male), businessName, pronounce (how to say the business name; Devanagari works), language, goal, notes, maxMinutes. Anything left out uses your settings on the AI Calls page. Languages: auto, hi, hinglish, en, ta, te, bn, mr, gu, pa, kn.

• One credit is one answered call up to 3 minutes, plus one per started minute after that. Unanswered calls are free.
• Calls go out between 09:00 and 21:00 IST, and once per number per 24 hours.
• 402 no credits left (call packs), 429 daily cap or the same number within 24 hours, 403 a plan below Starter.
• Only a QUEUED call can be cancelled; otherwise 409.

Webhooks

Outgoing webhooks POST JSON to your HTTPS endpoint, for n8n, Make, Zapier or your own app.

Create one with name, url and events (an array). The URL must be public https://; private and internal addresses are refused. The response includes a secret. Save it: you need it to check signatures.

POST /webhooks/:id/test sends { "event": "test", "data": {…}, "timestamp": "…" } with an X-ViralDM-Signature header: the HMAC-SHA256 of the raw body, in hex, keyed with your secret.

const crypto = require('crypto');

// Express: app.post('/viraldm', express.raw({ type: 'application/json' }), handler)
function verified(req) {
  const expected = crypto.createHmac('sha256', process.env.VIRALDM_WEBHOOK_SECRET)
    .update(req.body).digest('hex');
  const got = String(req.headers['x-viraldm-signature'] || '');
  return got.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected));
}

import hmac, hashlib, os

def verified(raw_body: bytes, signature: str) -> bool:
    expected = hmac.new(os.environ['VIRALDM_WEBHOOK_SECRET'].encode(),
                        raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature or '')

Business events: leads, bookings and sales

Seven events fire when ViralDM itself produces something worth acting on. They are what Zapier, Make and Pabbly Connect flows usually start from: create a "catch hook" in the tool, add its URL as a webhook here, and subscribe to the events you want.

• lead.captured: a DM gave an email or a phone number ViralDM did not have.
• bio.lead: someone left their details on your bio page.
• form.submitted: a form was answered.
• booking.created: a call was booked on your bio page, in a DM, or on a connected Calendly.
• order.paid: a store order was paid.
• payment.received: a DM sale was paid through your payment gateway.
• mention.story: someone mentioned you in their Instagram story. Carries username, a ready-to-read message and url, the Instagram thread where you can repost it.

{
  "event": "lead.captured",
  "type": "lead.captured",
  "name": "Asha K",
  "username": "asha.k",
  "email": "[email protected]",
  "phone": "+919800000000",
  "platform": "INSTAGRAM",
  "message": "Wants the course link",
  "source": "viraldm",
  "at": "2026-10-17T10:00:00.000Z"
}

Fields that are not known are left out. order.paid and payment.received also carry amount in rupees. Every delivery is signed with X-ViralDM-Signature as above.

DM events: dm.received and dm.sent

dm.received fires when a DM arrives on a connected account. dm.sent fires after every DM ViralDM sends, whether from an automation, the inbox, the API or MCP. Subscribe with "events": ["dm.received", "dm.sent"]. A staff inbox built on the API can rely on these instead of polling, and webhook deliveries do not count against your API calls.

{
  "event": "dm.received",
  "conversationId": "…",
  "subscriberId": "…",
  "platform": "INSTAGRAM",
  "accountId": "…",
  "messageId": "…",
  "text": "Is the course still available?",
  "attachments": [ { "type": "image", "url": "https://…" } ],
  "createdAt": "2026-10-15T10:00:00.000Z"
}

• attachments lists every media item of the message, each typed image, video, voice_note or file (on dm.sent also audio). A voice note recorded in Instagram arrives as voice_note, and its transcript is in text. Shared posts, reels and story mentions are not included.
• Attachment URLs are Meta's own links and expire. Download the file when the event arrives.
• Every delivery carries X-ViralDM-Event, X-ViralDM-Delivery, X-ViralDM-Timestamp and X-ViralDM-Signature (as above). A delivery that fails with a network error, 429 or a 5xx is retried twice, after 2 and 10 seconds, with the same X-ViralDM-Delivery id so you can drop duplicates.
• Missed something? Read it back with GET /conversations and GET /conversations/:id/messages (see AI Brain and inbox).

All other endpoints

Everything else on /api/v1, grouped. Same key, same rules. The MCP tools on the MCP page describe most of them in more detail.

AI and content

AI routes need an app plan with AI. Starter has 30 generations a month; Growth and up are unlimited.

Analytics, templates, coupons, tests

AI Brain and inbox

Growth tools

Account, trust and integrations

MCP server

If you want an AI assistant to use ViralDM rather than write code against it, use the MCP server at https://mcp.viraldm.app/mcp. It turns this API into 58 tools that Claude, ChatGPT, Cursor, Gemini CLI and n8n can call, with OAuth sign-in. Its calls count towards the same quota.

Set up the MCP server →

Help

Stuck on something, or found a mistake in these docs? Write to us with the request you sent and the response you got. Never include your API key.