Perfect Msg API
Get an API keyAdd contacts, send texts and run campaigns from your own systems.
Get started
The workspace owner creates keys in Settings → Integrations. You see a key only once. Send it on every request:
curl https://app.perfectmsg.com/api/v1/workspace \
-H "Authorization: Bearer pm_live_…"Requests and responses are JSON, up to 10 MB. Limit: 300 requests per minute per key. Errors look like { "error": { "code": "opted_out", "message": "…" } }.
Use US or Canadian phone numbers in any common format. Tags ignore upper and lower case and are cut to 60 characters.
Money is in micros unless the name says otherwise: 1,000,000 micros is $1. A deal's value is sent in dollars and comes back as valueCents.
Workspace
GET/api/v1/workspace
Your workspace, balance, sending status and contact counts.
Contacts
POST/api/v1/contacts
Add up to 5,000 contacts per request, matched by phone number. Set onExisting to "skip" (default) to leave existing contacts alone, or "update" to save the values you send and add tags. Blank values are ignored.
{
"contacts": [
{ "phone": "+15125550100", "firstName": "Ana", "lastName": "Diaz",
"email": "ana@example.com", "company": "Diaz Plumbing", "tags": ["vip"] }
],
"tags": ["roof-quote", "11/04/26"],
"onExisting": "skip"
}Returns
{ "received": 1, "created": 1, "existing": 0, "existingAction": "skip",
"duplicatesInRequest": 0, "invalidCount": 0, "invalid": [] }GET/api/v1/contacts?tag=roof-quote&excludeTag=no-text&q=&limit=100&after=
List contacts, oldest first. Filter by tag, leave out a tag, or search. When nextCursor isn't null, pass it as ?cursor= (or ?after=) for the next page.
POST/api/v1/contacts/tags
Add or remove tags on existing contacts by phone number.
{ "phones": ["+15125550100"], "add": ["hot"], "remove": ["cold"] }GET/api/v1/tags
Every tag with its contact count, most used first. Returns truncated: true past 1,000 tags.
Contact details
GET/api/v1/contacts/{id}
One contact with their notes and deal.
PATCH/api/v1/contacts/{id}
Change only the fields you send.
{ "firstName": "Marcus", "company": "Bell Roofing", "tags": ["vip"] }GET/api/v1/contacts/{id}/notes
A contact's notes, newest first.
POST/api/v1/contacts/{id}/notes
Add a note.
{ "body": "Prefers mornings" }POST/api/v1/contacts/opt-out
Opt a number out, the same as a STOP reply.
{ "phone": "+15125550100" }Messages
POST/api/v1/messages
Send one text. from is optional if the contact already has a conversation or you have one active number. Opted-out contacts are refused. Tags like {{contact.first_name | there}} and {Hi|Hey} are filled in, the same as in a campaign; a tag we can't fill is a 400.
{ "to": "+15125550100", "body": "Hi Ana, your quote is ready.", "from": "+15555550100" }Returns
202 { "id": "…", "status": "created", "from": "+15555550100", "to": "+15125550100", "segments": 1 }Webhooks
POST/api/v1/webhooks
Get every incoming text sent to your URL, including STOP. The URL must be https. We POST { "event": "message.received", "id": "…", "createdAt": "…", "data": { "from", "to", "body", "mediaUrls", "keyword", "campaignId", "contact" } }. keyword is opt_out, opt_in, help or none. Answer with any 2xx within 60 seconds. Anything else is retried for about 7 hours, so the same id can arrive twice. To check a delivery came from us, take the X-PerfectMsg-Timestamp header, add a dot and the raw body, and compare the HMAC-SHA256 of that (made with your secret, in hex) to X-PerfectMsg-Signature. The secret is shown once.
{ "url": "https://example.com/texts" }Returns
201 { "id": "…", "url": "https://example.com/texts", "secret": "whsec_…" }GET/api/v1/webhooks
Your webhook URLs.
DELETE/api/v1/webhooks/{id}
Stop sending to a URL. Deliveries still waiting are dropped.
Sending and history
POST/api/v1/messages/batch
Send up to 1,000 texts. Each row reports its own result.
{ "messages": [{ "to": "+15125550100", "body": "Hi" }] }GET/api/v1/messages
The message log, newest first. Filter with q, direction (inbound, outbound), status (delivered, sent, failed, received, cancelled), campaign, number (a phone number), and from and to (dates like 2026-11-30, not phone numbers). A value we can't read is a 400. range is today, all, or a number of days. A search with no dates looks at the last 90 days; add range=all for everything. Page with before (or cursor), using nextBefore (or nextCursor) from the last page. limit is 1 to 500, default 100. A text that came in another language also has translatedBody (in English) and translatedFrom (the language code, like es); body is always what they sent.
GET/api/v1/conversations
Every text with one person across all your numbers. Send ?phone=. limit is 1 to 500, default 100. Texts have translatedBody and translatedFrom when they came in another language, null otherwise.
GET/api/v1/conversations/inbox
Your conversations, 40 at a time, newest first, like the Conversations page. view is positive, unread, all, starred, archived or recent (default all). Filter with q (name, company or phone), number (one of your numbers) and assigned (a team member's id). sort is newest or oldest. Page with after, using next from the last page, or go back with before, using previous. lastActivity.translatedBody is there when the last text came in another language.
GET/api/v1/conversations/unread
How many conversations are unread, the same number as the app shows.
Returns
{ "count": 12, "more": false, "badge": "12" }GET/api/v1/templates
Your saved messages.
POST/api/v1/templates
Save a message. Saving an existing name updates it.
{ "name": "Intro", "body": "Hi {{contact.first_name | there}}" }DELETE/api/v1/templates/{id}
Delete a saved message.
Numbers
GET/api/v1/numbers
Your numbers and their texting approval status.
DELETE/api/v1/numbers/{id or +1 phone}
Remove a number from your workspace for good. It stops sending, taking calls and billing, and you can't get it back. A running or paused campaign still sending from it must move to another number first.
Returns
{ "id": "…", "number": "+15551234567", "status": "released" }POST/api/v1/numbers/{id or +1 phone}/campaign
Link a number to an approved campaign. Send the campaign id or carrier id, like CABC123. The number turns on when the carrier confirms.
{ "campaign": "CABC123" }Campaigns
POST/api/v1/campaigns
Create a draft. includeTags picks contacts with any of those tags. excludeTags always leaves contacts out. To text every contact, leave includeTags empty and set allContacts: true. backupText (off by default) sends a step's backup once to someone a phone company blocked that step for as spam; a step with no backup gets one written. Nothing sends until launch.
{
"name": "Quote follow-up",
"sender": "+15555550100",
"steps": [
{ "body": "Hi {{contact.first_name | there}}, still want that roof quote?", "delayMinutes": 0 },
{ "body": "Just checking in, {{contact.first_name | there}}.", "delayMinutes": 1440 }
],
"stopOnResponse": true,
"includeTags": ["roof-quote"],
"excludeTags": ["no-text"],
"scheduledAt": null,
"pace": { "messages": 20, "everyMinutes": 1 }
}GET/api/v1/campaigns
List campaigns with their audience and stats. stats.waiting is how many texts are held by T-Mobile's daily limit and go out on a later day.
GET/api/v1/campaigns/{id}
One campaign, with the same stats. While stats.waiting is above 0 the campaign is not finished.
PUT/api/v1/campaigns/{id}
Replace a draft's settings (same body as create).
PATCH/api/v1/campaigns/{id}
Change the words of a paused campaign. Send one body for each message, in order. People not texted yet get the new wording.
{ "steps": [{ "body": "New text" }] }POST/api/v1/campaigns/{id}/senders
Move a paused campaign to other numbers. Everyone not texted yet sends from the new numbers, split evenly when you give several. Returns the campaign and how many people moved.
{ "senders": ["+15551234567"] }POST/api/v1/campaigns/{id}/remove-recipients
Take people with any of these tags out of a paused campaign, if they still have a text coming. Returns how many were removed.
{ "tags": ["no-text"] }POST/api/v1/campaigns/{id}/launch
Start sending to contacts who match the tags right now. Opt-outs and contacts added later are left out. With quiet hours on, texts launched outside your sending hours wait for the next window, so status can be running with nothing sent yet.
Returns
{ "id": "…", "status": "running", "recipients": 28225, "skipped": 0 }POST/api/v1/campaigns/{id}/pace
Change how fast a campaign sends, even while it is sending. Use null for full speed. Texts are spread evenly. effectivePace is how fast it really goes: never faster than your number allows.
{ "pace": { "messages": 500, "everyMinutes": 60 } }Returns
{ "id": "…", "pace": { "messages": 500, "everyMinutes": 60 }, …,
"effectivePace": { "messagesPerMinute": 8.33, "topSpeedPerMinute": 216, "limitedByCarrier": false } }POST/api/v1/campaigns/{id}/backup-text
Turn backup texts on or off, even while a campaign sends. When a phone company blocks one of its texts as spam, that person gets the step's backup once, 11 seconds later. It is billed like any text. Send one backup for each message, in order, or "" for none. Leave steps out to have a backup written for each message that has none.
{ "on": true, "steps": [{ "backup": "Hi {{contact.first_name}}, want a quick quote?" }] }POST/api/v1/campaigns/{id}/pause
Pause a running campaign.
POST/api/v1/campaigns/{id}/resume
Resume a paused campaign.
Deals
GET/api/v1/deals/stages
The stages on your board, in order.
GET/api/v1/deals
Deals with their contact, up to 500 at a time (?limit=). Add ?stage={stageId} for one stage. When nextAfter isn't null, pass it as ?after= for the next page.
POST/api/v1/deals
Put a contact on the board, or update their deal. With no stage, it goes in the first one.
{ "contactId": "…", "stageId": "…", "value": 2500 }PATCH/api/v1/deals/{contactId}
Change a deal's stage or value.
{ "stageId": "…", "value": 5000 }DELETE/api/v1/deals/{contactId}
Take a contact off the board.
Calendar
GET/api/v1/ai-assistant
The AI Appointment Setter's setup: name, voice, instructions, knowledge, goal, booking calendar, mode and whether it's on.
PATCH/api/v1/ai-assistant
Changes only the fields sent, with the same checks as Save in the app. Turning it on (enabled: true) needs the AI Appointment Setter on. Each save is a version you can go back to.
{ "name": "Christina", "goal": "book", "bookingMode": "calendar", "calendarId": "…", "mode": "auto", "enabled": true }GET/api/v1/calendars
Your calendars with their people, in list order. Add ?active=true for only the ones taking bookings.
POST/api/v1/calendars
Makes a calendar: name, memberIds (team userIds, top first), durationMinutes, slotIntervalMinutes, minNoticeMinutes (under an hour is fine, like 15), bookingWindowDays, locationType and the rest of the calendar's settings. It starts with the usual reminder texts.
{ "name": "Intro call", "memberIds": ["…"], "durationMinutes": 20, "slotIntervalMinutes": 15, "minNoticeMinutes": 15, "bookingWindowDays": 14 }GET/api/v1/calendars/{id}
One calendar with its people.
PATCH/api/v1/calendars/{id}
Changes only the fields sent, with the same fields as making one.
GET/api/v1/calendars/{id}/slots
Open start times from ?from= to ?to= (dates like 2026-11-12, up to 31 days), grouped by day in ?timezone= (your workspace's timezone if left out). When moving an appointment, add ?moving={appointmentId} so its own time shows as open.
GET/api/v1/calendars/{id}/reminders
The calendar's reminder texts, in order, each with its message and when it goes out.
POST/api/v1/calendars/{id}/reminders
Adds a reminder text: body (spots like {{contact.first_name}}, {{location.name}}, {{appointment.date}}, {{appointment.time}}, {{appointment.address}}, {{appointment.video_link}}), timing (booked, before with minutesBefore, or day_of with sendTime like "09:00" and onlyFrom like "12:00" or null), and enabled. Upcoming appointments get it too.
{ "body": "Hi {{contact.first_name}}, see you at {{appointment.time}}!", "timing": "before", "minutesBefore": 120 }PATCH/api/v1/calendars/{id}/reminders/{reminderId}
Changes only the fields sent. Upcoming appointments move to the new time; a text already sent is never sent again.
DELETE/api/v1/calendars/{id}/reminders/{reminderId}
Removes a reminder. Texts it already sent stay in the conversation.
GET/api/v1/calendar-accounts
Each team member's connected Google Calendar or Outlook: provider (google or microsoft), the account's email, and status (active, or needs_reconnect when they need to sign in again). Bookings are written to it and its busy times block bookings. Each person connects their own in the app, on My hours.
DELETE/api/v1/calendar-accounts/{id}
Disconnects one. Its sign-in and the busy times read from it are deleted. Appointments already on that calendar stay there.
GET/api/v1/appointments
Appointments, soonest first, up to 500 a page (?limit=). When nextAfter is not null, send it back as ?after= for the next page. Filter with ?from=, ?to= (date and time), ?calendarId=, ?userId=, ?contactId=, and ?status= (booked, cancelled, no_show, completed, or open for all but cancelled).
POST/api/v1/appointments
Book a contact. The calendar picks who takes it unless you send userId. For a calendar that meets at their place, send address too. Answers to the calendar's own questions (its formFields) go in answers, by question id. If someone else just took that time you get a 409.
{ "calendarId": "…", "contactId": "…", "startsAt": "2026-11-12T15:00:00Z", "notes": "Wants a quote" }GET/api/v1/appointments/{id}
One appointment.
PATCH/api/v1/appointments/{id}
Move it with startsAt, or say how it went with status.
{ "startsAt": "2026-11-13T16:00:00Z" } or { "status": "completed" }POST/api/v1/appointments/{id}/cancel
Cancel it.
Websites
GET/api/v1/sites
Your websites. Up to 10 can be on at once.
POST/api/v1/sites
Make a website for a business. It gives you the links carriers ask for. Send brandId for a business already registered. Nothing is charged, and carriers get this site's address as that business's website. If they can't be reached, no site is made and you get a 409. Send businessName and email for a business that isn't registered yet, and type the url you get back as its website in Trust Center. Sending this again updates that same site, and nothing goes to carriers. about must be a few real words. You can also send the details below under PATCH, like services, hours and socials. For a business that isn't registered, ownWebsiteUrl makes only the sign-up page, with a menu that links to that website. signupUrl is the page people sign up for texts on.
{ "brandId": "…", "about": "We fix roofs in Chicago." }
{ "businessName": "Acme Roofing", "legalName": "Acme Roofing LLC", "about": "We fix roofs in Chicago.",
"email": "jo@acme.com", "phone": "+13125550123", "address": "12 Main St, Chicago, IL 60601", "state": "IL" }Returns
{ "id": "…", "brandId": null, "slug": "acme-roofing", "url": "https://app.perfectmsg.com/site/acme-roofing",
"businessName": "Acme Roofing", "legalName": "Acme Roofing LLC", "about": "We fix roofs in Chicago.",
"purposes": ["marketing", "care"], "email": "jo@acme.com", "phone": "+13125550123",
"address": "12 Main St, Chicago, IL 60601", "state": "IL", "effectiveOn": "2026-11-06",
"signupUrl": "https://app.perfectmsg.com/site/acme-roofing/subscribe", "services": [], "hours": null, "socials": null,
"logoUrl": null, "photos": [], "heroUrl": "https://app.perfectmsg.com/site-stock/construction-1.webp", "hasLogo": false,
"hasOwnPrivacy": false, "hasOwnTerms": false, "enabled": true, "createdAt": "…", "updatedAt": "…" }GET/api/v1/sites/{id}
One website.
PATCH/api/v1/sites/{id}
Change only the fields you send. The address of the site never changes. purposes can hold marketing, care, account, delivery and login. A campaign still live on this business keeps its purposes on the site. privacyText and termsText replace ours and need at least 100 letters. We always keep the texting and contact sections under them. Send null to use ours again. Set enabled to false to turn the site off. The other details show on the site only when set: tagline, services (a list of short names), areaServed, registrationNumber (the state's number for the business), formationState (the two-letter state it was formed in), hours (like [{ "day": "mon", "open": "08:00", "close": "17:00" }], a day left out is closed), socials (https links for facebook, instagram, linkedin, x, youtube, tiktok, google or yelp), accent (blue, green, teal, red, orange or purple), heroPhoto (0 to 5, one of the photos added in Trust Center, or null for a free photo), and ownWebsiteUrl, ownPrivacyUrl and ownTermsUrl. Once carriers have the site, ownWebsiteUrl can change but can't be set or cleared. Photos and the logo are added in Trust Center.
{ "about": "We fix and replace roofs in Chicago.", "phone": null, "purposes": ["care"], "services": ["Roof repair", "New roofs"], "enabled": true }GET/api/v1/sites/{id}/campaign-text?type=MARKETING
The text to send carriers for a campaign, made from this website: description, how people sign up, links, samples and replies. type is MARKETING, CUSTOMER_CARE, ACCOUNT_NOTIFICATION, DELIVERY_NOTIFICATION, 2FA, LOW_VOLUME_MIXED or SOLE_PROPRIETOR. You get a 409 while the website is off, because its links wouldn't work.
Reports and account
GET/api/v1/reports
Totals, daily counts, failure reasons, campaigns and numbers. Send ?days=7, 30 or 90.
GET/api/v1/brands
Your brands and their approval status. approved is true once a brand can have campaigns. needsTextCode is true for a sole proprietor who still has to confirm their text code, and textCodeMobileLast4 shows which mobile it goes to.
POST/api/v1/brands/{id}/text-code
Sole proprietors only. Text a new code to the mobile on this brand. Free. Up to 5 an hour, 10 a day and 15 for each brand. Past that you get a 429. A mobile carriers won't text gets a 422 with mobile_not_reachable. Other brands get a 409.
Returns
{ "sent": true }POST/api/v1/brands/{id}/text-code/confirm
Sole proprietors only. Confirm the code they got. Free. A wrong or expired code gets a 400 with wrong_code. A sole proprietor can't have campaigns until this is done.
{ "code": "123456" }Returns
{ "confirmed": true, "approved": false }GET/api/v1/billing/transactions
Credit added and spent, newest first.
Team
GET/api/v1/team
Your people and open invites.
GET/api/v1/team/{id}/hours
When this person takes appointments: timezone and weekly, 7 days Sunday first, each a list of { start, end } like "09:00".
PUT/api/v1/team/{id}/hours
Replaces their hours. An empty day is a day off.
{ "timezone": "America/Chicago", "weekly": [[], [{ "start": "09:00", "end": "17:00" }], [], [], [], [], []] }GET/api/v1/team/permissions
Every permission and preset, and what a key can give.
POST/api/v1/team/invites
Invite someone by email. A key can give only what a key can do, so a preset loses anything else. The reply shows what they got.
{ "email": "ana@example.com", "preset": "team_member" }Returns
201 { "id": "…", "email": "ana@example.com", "status": "invited", "permissions": ["conversations.view", "…"], "expiresAt": "…" }POST/api/v1/team/invites/{id}/resend
Send a new link. The old one stops working.
DELETE/api/v1/team/invites/{id}
Cancel an invite.
PATCH/api/v1/team/{id}
Change what someone can do. A key can't change someone who has more than a key can give.
{ "permissions": ["contacts.view"], "onlyAssigned": false }DELETE/api/v1/team/{id}?reassignTo=
Remove someone. They are signed out now. Their conversations go to reassignTo, or to nobody. A key can't remove the owner or anyone the owner gave owner-only switches.
Suggestions
GET/api/v1/suggestions?sort=top&page=1&limit=20
The ideas board, shared by every workspace. sort is top (highest score first) or new. limit is 1 to 100. Each idea has its text, label, score, and age, and never says who posted it. yourPending lists this workspace's API posts that are not on the board.
POST/api/v1/suggestions
Post an idea. We check every post first, so it starts as checking and shows on the board once it passes. title can be 120 characters and details (optional) can be 1,000. Answers 429 when you have posted too many today.
{ "title": "Let me sort contacts by tag", "details": "It would save me time." }Returns
201 { "id": "…", "title": "Let me sort contacts by tag", "details": "It would save me time.", "status": "checking", "reason": null, "createdAt": "…" }POST/api/v1/suggestions/{id}/vote
Set your vote on an idea to up, down, or none. Sending the same vote twice changes nothing. Your API keys vote as the account owner, so they all share one vote with the owner.
{ "vote": "up" }Returns
{ "score": 4, "yourVote": "up" }Voice channels
GET/api/v1/rooms
Your voice channels, Team Chat first. Each has an inviteUrl anyone can open in a browser, with no account or download.
POST/api/v1/rooms
Make a channel and its invite link. A workspace can have 5 channels, Team Chat included. Needs an active plan.
{ "name": "Team call" }Returns
201 { "id": "…", "name": "Team call", "inviteUrl": "https://app.perfectmsg.com/meet/…",
"createdAt": "…", "updatedAt": "…" }PATCH/api/v1/rooms/{id}
Rename a channel. Needs an active plan.
{ "name": "Sales call" }DELETE/api/v1/rooms/{id}
Remove a channel. Anyone in a call there is taken out, and its link stops working. Team Chat can't be removed.
POST/api/v1/rooms/{id}/invite-link
Replace a channel's link. The old link stops working right away, and guests who came in with it are taken out. Returns the room with its new inviteUrl.