Perfect Msg

Perfect Msg API

Get an API key

Add 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.