Registration API
Automate 10DLC brand, campaign, and number registration with the /v1/sms/10dlc endpoints.
Everything in the registration walkthrough is available programmatically. Base URL https://api.speko.dev, authenticated with your API key.
Reading needs the speko:read scope. Every call that saves, submits, verifies, or assigns needs speko:compliance. A signed-in user must also be an owner or admin of the workspace. Other callers get 403 with code INSUFFICIENT_SCOPE or ORG_ADMIN_REQUIRED.
Only an owner or admin can create an API key with speko:compliance. A key created before that rule no longer carries the scope, and a legacy full-access key can read a registration but not change it. In either case an owner or admin creates a new key.
Paid steps charge Telnyx's fee at cost. Each one needs the fee plus $10 available, or it returns 402 with code INSUFFICIENT_CREDITS before anything reaches Telnyx:
{ "error": "This needs at least $55.00 available: the $45.00 fee plus a $10.00 minimum balance. Add credits and try again.", "code": "INSUFFICIENT_CREDITS", "feeUsd": 45, "requiredUsd": 55, "availableUsd": 30 }See registration fees for the amounts.
Overview
curl https://api.speko.dev/v1/sms/10dlc \
-H "Authorization: Bearer $SPEKO_API_KEY"Returns the full registration state:
{
"ownBrand": { "status": "verified", "identityStatus": "VERIFIED", "profile": { "..." : "..." }, "reviewErrors": [], "submittedAt": "2026-07-01T22:04:11.000Z" },
"ownCampaign": { "status": "active", "useCase": "ACCOUNT_NOTIFICATION", "reviewErrors": [], "submittedAt": "2026-07-02T18:30:00.000Z" },
"sharedCampaign": { "available": false, "label": null, "campaignId": null, "status": null },
"numbers": [
{ "id": "pn_...", "e164": "+15551234567", "smsEligible": true, "smsAssignmentStatus": "ASSIGNED", "assignedTo": "own", "...": "..." }
],
"smsReady": true,
"activeCampaignSource": "own",
"fees": { "availableBalanceUsd": 120.5, "brandRegistrationUsd": 4.5, "brandRegistrationCharged": true, "campaignReviewUsd": 15, "campaignPrepaidMonths": 3, "minimumBalanceHeadroomUsd": 10 }
}smsReady is true once at least one number is assigned to a currently approved campaign whose monthly fee is neither suspended nor ended. Telnyx reports status changes to Speko, and Speko also checks every 15 minutes while a registration is under review and every six hours once the campaign is approved, so the overview stays current without resubmitting anything.
ownBrand.kind is standard or sole_proprietor. ownBrand.otpRequired is true while a sole proprietor brand waits for its code. ownCampaign.billing holds the monthly fee state: status is current, grace (a month is unpaid and SMS sends until graceEndsAt), suspended (sending paused until the month is paid), or ended. ownCampaign.resubmit is appeal or recreate when a rejected campaign can be resubmitted. ownCampaign.resumeBillingUsd is the one-month fee that resumes billing for a campaign Telnyx approved after its billing ended, and null otherwise. For an appeal, ownCampaign.lockedFields holds the fields Telnyx cannot change on the submitted campaign, with their registered values (null for one that was left empty).
Brand
Save the business profile, then submit it to the carriers:
curl -X PUT https://api.speko.dev/v1/sms/10dlc/brand \
-H "Authorization: Bearer $SPEKO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"legalName": "MoonAI Inc",
"displayName": "MoonAI",
"entityType": "PRIVATE_PROFIT",
"vertical": "TECHNOLOGY",
"ein": "365142965",
"website": "https://example.com/",
"country": "US",
"street": "131 Continental Dr Suite 305",
"city": "Newark",
"state": "DE",
"postalCode": "19713",
"supportEmail": "support@example.com",
"supportPhone": "+15551234567",
"authorizedContact": {
"firstName": "Askhat", "lastName": "Adkhamov",
"email": "founder@example.com", "phone": "+15551234567"
}
}'
curl -X POST https://api.speko.dev/v1/sms/10dlc/brand/submit \
-H "Authorization: Bearer $SPEKO_API_KEY"All fields are required except ein (required in practice for every entity type except sole proprietors) and country (defaults to US). Phones are E.164. legalName must match the IRS record for the EIN.
The first /brand/submit of a business brand charges the $4.50 brand registration fee. Re-POSTing it updates the registered brand at no charge. The brand is ready when status is "verified" (carrier status OK with identity VERIFIED or VETTED_VERIFIED). A registered brand cannot switch between a business and a sole proprietor (409 code BRAND_KIND_LOCKED), and PUT /brand returns 409 code SMS_10DLC_OPERATION_IN_PROGRESS while a brand submission is in flight.
Sole proprietor
A sole proprietor brand uses "entityType": "SOLE_PROPRIETOR" and has no legalName or ein. website and supportPhone are optional. authorizedContact is the person, and authorizedContact.phone must be a US or Canadian mobile. Telnyx texts the verification code to it.
curl -X POST https://api.speko.dev/v1/sms/10dlc/brand/submit \
-H "Authorization: Bearer $SPEKO_API_KEY"
curl -X POST https://api.speko.dev/v1/sms/10dlc/brand/otp \
-H "Authorization: Bearer $SPEKO_API_KEY"
curl -X POST https://api.speko.dev/v1/sms/10dlc/brand/otp/verify \
-H "Authorization: Bearer $SPEKO_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "pin": "123456" }'Submitting a sole proprietor brand charges nothing. POST /brand/otp sends the code and POST /brand/otp/resend sends it again; both return 202. GET /brand/otp returns deliveryStatus: NOT_SENT, PENDING, DELIVERED_HANDSET, DELIVERY_FAILED, VERIFIED, or EXPIRED. A code expires after 24 hours. POST /brand/otp/verify charges the $4.50 brand fee when Telnyx accepts the code and returns the brand. A wrong or expired code returns 400 with code OTP_INVALID and charges nothing. A code sent while another check is still waiting on Telnyx returns 409 with code SMS_10DLC_OPERATION_IN_PROGRESS; send it again once that check finishes.
Optional enhanced vetting after a business brand is submitted (sole proprietors get 409 code VETTING_NOT_AVAILABLE):
curl -X POST https://api.speko.dev/v1/sms/10dlc/brand/vetting \
-H "Authorization: Bearer $SPEKO_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "vettingClass": "STANDARD" }'Campaign
Save the campaign profile, check the price, then submit:
curl -X PUT https://api.speko.dev/v1/sms/10dlc/campaign \
-H "Authorization: Bearer $SPEKO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"useCase": "ACCOUNT_NOTIFICATION",
"description": "Appointment confirmations and reminders sent by our AI receptionist.",
"messageFlow": "Customers book an appointment by phone and verbally agree to receive a confirmation text and reminder texts for their visit.",
"optInKeywords": "START",
"optInMessage": "MoonAI: you are subscribed to appointment updates. Msg frequency varies. Msg & data rates may apply. Reply HELP for help, STOP to opt out.",
"helpKeywords": "HELP",
"helpMessage": "MoonAI: for help contact support@example.com. Reply STOP to opt out.",
"optOutKeywords": "STOP",
"optOutMessage": "MoonAI: you are unsubscribed and will receive no more messages.",
"sampleMessages": [
"MoonAI: your visit is confirmed for Jul 3 at 5:00 PM at 123 Main St. Reply STOP to opt out.",
"MoonAI: reminder, your visit is tomorrow at 5:00 PM. Reply C to confirm or STOP to opt out."
],
"embeddedLink": false,
"embeddedPhone": false,
"privacyPolicyLink": "https://example.com/privacy"
}'
curl https://api.speko.dev/v1/sms/10dlc/campaign/quote \
-H "Authorization: Bearer $SPEKO_API_KEY"
curl -X POST https://api.speko.dev/v1/sms/10dlc/campaign/submit \
-H "Authorization: Bearer $SPEKO_API_KEY"sampleMessages accepts 1-5 entries; submitting needs at least 2, and one for each of the subUsecases. A sole proprietor's campaign is saved with useCase SOLE_PROPRIETOR. MIXED and LOW_VOLUME campaigns need 2-5 subUsecases and SOLE_PROPRIETOR at least 1, for example ["CUSTOMER_CARE", "ACCOUNT_NOTIFICATION"]; the quote's subUseCases gives the exact range. Campaign submit requires a verified brand (400 code BRAND_NOT_READY otherwise). Quote and submit refuse content The Campaign Registry would reject before anything is charged (400 code CAMPAIGN_CONTENT_INVALID, each issue in problems): too few samples, a description or opt-in flow under 40 characters (or over 4096 and 2048), an auto-reply or sample under 20 characters (or over 320 and 1024), the wrong number of subUsecases, or an auto-reply without the disclosures carriers require (TCR code 861). The opt-in message must name the brand and include HELP and STOP instructions, the message frequency and "Msg & data rates may apply"; the HELP message the brand and a support email, phone number or website; the STOP message the brand and that no more messages will be sent. The brand is the one Telnyx registered, not a brand draft saved since. Without a privacyPolicyLink, the messageFlow must mention the privacy policy. An appeal cannot change the opt-in or STOP message or the privacyPolicyLink, so it checks only the HELP message and the opt-in flow, and only the link Telnyx registered counts. Carrier review takes 1-7 business days; the campaign is ready when status is "active", once the carriers provision it (MNO_PROVISIONED). A campaign Telnyx accepted for review (TCR_ACCEPTED) is still "pending".
GET /campaign/quote returns the exact charge for the next submission, using Telnyx's monthly fee for the use case:
{ "action": "create", "useCase": "ACCOUNT_NOTIFICATION", "reviewFeeUsd": 15, "monthlyFeeUsd": 10, "prepaidMonths": 3, "dueNowUsd": 45, "minimumBalanceUsd": 55, "availableBalanceUsd": 120.5, "sufficientBalance": true }Send the useCase and dueNowUsd of the quote you showed as quote, for example { "quote": { "useCase": "ACCOUNT_NOTIFICATION", "dueNowUsd": 45 } }. If the price changed since (another session edited the draft, or Telnyx's fee moved), the submit returns 409 with code CAMPAIGN_QUOTE_CHANGED and the current useCase and dueNowUsd, and charges nothing. A workspace has one campaign. Submitting again while it is under review or active returns 409 with code CAMPAIGN_ALREADY_SUBMITTED and charges nothing. A second submit sent while the first is still in flight returns 409 with code SMS_10DLC_OPERATION_IN_PROGRESS.
If the carriers reject the campaign, the prepaid months it never served are refunded (all three if it was never provisioned) and ownCampaign.resubmit says how to resubmit. For appeal (TELNYX_FAILED or MNO_REJECTED), Speko updates the sample messages, opt-in flow, and HELP message on the same campaign. If the update puts it back in review, that is the resubmission; otherwise Speko appeals it with your reason. The price uses the use case the campaign is registered under. Telnyx's campaign update carries only those three fields, so the other fields keep their registered values (ownCampaign.lockedFields). A draft that changes one of them, or drops a sample message the campaign was registered with, is refused with 409 and code CAMPAIGN_FIELDS_NOT_UPDATABLE, listing them in fields, before any price or charge. Send what you changed:
curl -X POST https://api.speko.dev/v1/sms/10dlc/campaign/submit \
-H "Authorization: Bearer $SPEKO_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "appealReason": "Added a privacy policy and terms to the opt-in page." }'Without appealReason an appeal returns 400 with code APPEAL_REASON_REQUIRED. For recreate (TCR_FAILED), Speko registers a new campaign. Every resubmission charges the $15 review fee plus three prepaid months.
Resume billing for a campaign approved later
A rejected or lapsed campaign stops billing and stops sending. If Telnyx approves it later anyway, it is active with billing.status ended, and it still does not send: it cannot be resubmitted, because it is not rejected. ownCampaign.resumeBillingUsd then shows what resuming costs: one month of the campaign's monthly fee, charged now. There is no review fee and no new campaign. Billing restarts as current, and the next month is charged 30 days later. Speko rereads a stopped campaign from Telnyx at least once a day, so a late approval shows up even when its notification was missed.
curl -X POST https://api.speko.dev/v1/sms/10dlc/campaign/billing/resume \
-H "Authorization: Bearer $SPEKO_API_KEY"It needs the fee plus $10 available (402 with code INSUFFICIENT_CREDITS otherwise). In any other state it returns 409 with code CAMPAIGN_BILLING_NOT_RESUMABLE and charges nothing. While a resubmission still awaits Telnyx it returns 409 with code SMS_10DLC_OPERATION_IN_PROGRESS, because that resubmission restarts billing when it is confirmed. Before charging, Speko reads the campaign from Telnyx again and decides on that status. If Telnyx cannot be reached it returns 502 with code TELNYX_CAMPAIGN_STATUS_FAILED and charges nothing.
Numbers
curl -X POST https://api.speko.dev/v1/sms/10dlc/numbers/{phoneNumberId}/assign \
-H "Authorization: Bearer $SPEKO_API_KEY"Assigns the number to your approved campaign (pass { "target": "shared" } to use Speko's shared campaign where available; with no body it prefers your own campaign, then shared). Phone number IDs come from GET /v1/phone-numbers or the numbers array in the overview. SIP-trunk imported numbers return 400 with code SMS_ASSIGNMENT_UNSUPPORTED_NUMBER. A sole proprietor campaign sends from one number: assigning a second returns 409 with code SOLE_PROPRIETOR_NUMBER_LIMIT.
smsAssignmentStatus values: PENDING_ASSIGNMENT, ASSIGNED, FAILED_ASSIGNMENT, PENDING_UNASSIGNMENT, FAILED_UNASSIGNMENT.
Error codes
| Code | Meaning |
|---|---|
INSUFFICIENT_SCOPE | The API key lacks speko:read (reads) or an owner- or admin-granted speko:compliance (changes) |
ORG_ADMIN_REQUIRED | The signed-in user is not an owner or admin of the workspace |
INSUFFICIENT_CREDITS | The balance is below the fee plus $10; nothing was charged |
SMS_10DLC_OPERATION_IN_PROGRESS | Another request of this workspace is still submitting the brand, verifying its code, or submitting the campaign; retry once it finishes |
PROFILE_REQUIRED | Save the brand/campaign draft before submitting |
BRAND_KIND_LOCKED | A registered brand cannot switch between a business and a sole proprietor |
NOT_SOLE_PROPRIETOR / BRAND_ALREADY_VERIFIED | OTP calls on a business brand, or on an already verified one |
OTP_INVALID | Wrong or expired code; nothing was charged |
VETTING_NOT_AVAILABLE | Sole proprietor brands are not vetted |
CAMPAIGN_ALREADY_SUBMITTED | The workspace's campaign is under review or active |
CAMPAIGN_QUOTE_CHANGED | The price differs from the quote sent; nothing was charged. Show the returned price and submit again |
APPEAL_REASON_REQUIRED | Resubmitting a rejected campaign needs appealReason |
CAMPAIGN_BILLING_NOT_RESUMABLE | Billing can be resumed only for an approved campaign whose billing ended; nothing was charged |
TELNYX_CAMPAIGN_STATUS_FAILED | Resuming billing could not read the campaign's status from Telnyx; nothing was charged. Retry later |
CAMPAIGN_FIELDS_NOT_UPDATABLE | An appeal's draft changes fields Telnyx cannot update on the submitted campaign, listed in fields; nothing was charged. Restore the values in ownCampaign.lockedFields |
CAMPAIGN_FEE_UNAVAILABLE | Telnyx did not price the use case; retry later |
SOLE_PROPRIETOR_NUMBER_LIMIT | A sole proprietor campaign already sends from another number |
BRAND_REQUIRED | Vetting requested before the brand was submitted |
BRAND_NOT_READY | Campaign submitted before the brand is verified |
PHONE_NUMBER_NOT_FOUND | The phone number id doesn't belong to this workspace |
OWN_CAMPAIGN_NOT_READY / SHARED_CAMPAIGN_UNAVAILABLE / NO_ELIGIBLE_CAMPAIGN | No approved campaign to assign the number to |
SMS_ASSIGNMENT_UNSUPPORTED_NUMBER | SIP-trunk numbers can't join a Speko 10DLC campaign |
TELNYX_BRAND_SUBMIT_FAILED / TELNYX_CAMPAIGN_SUBMIT_FAILED / TELNYX_NUMBER_ASSIGNMENT_FAILED / TELNYX_VETTING_FAILED / TELNYX_OTP_SEND_FAILED / TELNYX_OTP_VERIFY_FAILED | Carrier-side rejection or outage. A fee charged for the step is refunded. Check the details and retry |
TELNYX_OUTCOME_UNKNOWN | Telnyx did not confirm a paid step (502). The fee stays charged until Speko completes the step with Telnyx or refunds it, within 30 minutes. For a resubmission still rejected, Speko sends your new content again if Telnyx may not have it, then the appeal, and refunds the fee only if Telnyx refuses one of them. Don't resubmit |
VALIDATION_ERROR | Field validation failed — see the issues array |