Verify Services API Live

A Verify Service groups the settings for one use case, brand, or app: enabled channels, code length and TTL, country allowlist, send caps, SMS template variant, and custom email copy. This page covers creating, listing, updating, deleting, and previewing services, plus the webhook endpoints scoped to them. Every endpoint below accepts the same Bearer mk_ key with the verify scope you already use to send and check codes.

Authentication

Authorization: Bearer mk_live_... with the verify scope, same as the rest of the Verify API. A missing or invalid key returns 401 unauthorized; a valid key without the verify scope returns 403 insufficient_scope.

Create a service

The first service created in a workspace automatically becomes the default (the service POST /v1/verify resolves to when no serviceId is given). Later services must be made default explicitly, with a PATCH.

Body parameters

curl -X POST https://api.message.com/v1/verify/services \
  -H 'Authorization: Bearer mk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "friendlyName": "Acme",
    "enabledChannels": ["email", "sms", "voice"],
    "codeLength": 6,
    "allowedCountries": ["US", "CA"]
  }'

const res = await fetch('https://api.message.com/v1/verify/services', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer mk_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ friendlyName: 'Acme' }),
});
const { service } = await res.json();

{
  "service": {
    "id": "vs_7hK2pQmN4rT8sX1c",
    "friendlyName": "Acme",
    "isDefault": true,
    "enabledChannels": ["email", "sms", "voice"],
    "codeLength": 6,
    "codeTtlSeconds": 600,
    "allowedCountries": ["US", "CA"],
    "perMinuteCap": 10,
    "perDayCap": 1000,
    "smsTemplateVariant": "standard",
    "emailSubject": null,
    "emailBodyHtml": null,
    "notes": null,
    "createdAt": "2026-07-25T18:04:11.000Z",
    "updatedAt": "2026-07-25T18:04:11.000Z"
  }
}

List services

All services in the calling workspace, no pagination.

curl -X GET https://api.message.com/v1/verify/services \
  -H 'Authorization: Bearer mk_live_...'

{
  "services": [
    {
      "id": "vs_7hK2pQmN4rT8sX1c",
      "friendlyName": "Acme",
      "isDefault": true,
      "enabledChannels": ["email", "sms", "voice"],
      "codeLength": 6,
      "codeTtlSeconds": 600,
      "allowedCountries": ["US", "CA"],
      "perMinuteCap": 10,
      "perDayCap": 1000,
      "smsTemplateVariant": "standard",
      "emailSubject": null,
      "emailBodyHtml": null,
      "notes": null,
      "createdAt": "2026-07-25T18:04:11.000Z",
      "updatedAt": "2026-07-25T18:04:11.000Z"
    }
  ]
}

Get a service

Returns a single service by its vs_... id. An id that does not resolve in this workspace returns 404 service_not_found.

{
  "service": {
    "id": "vs_7hK2pQmN4rT8sX1c",
    "friendlyName": "Acme",
    "isDefault": true,
    "enabledChannels": ["email", "sms", "voice"],
    "codeLength": 6,
    "codeTtlSeconds": 600,
    "allowedCountries": ["US", "CA"],
    "perMinuteCap": 10,
    "perDayCap": 1000,
    "smsTemplateVariant": "standard",
    "emailSubject": null,
    "emailBodyHtml": null,
    "notes": null,
    "createdAt": "2026-07-25T18:04:11.000Z",
    "updatedAt": "2026-07-25T18:04:11.000Z"
  }
}

Update a service

Every body field is optional; only the fields you send are changed. Adding a non-live channel to enabledChannels returns 422 channel_not_available, same as create. Unset fields keep their current value.

Additional field

curl -X PATCH https://api.message.com/v1/verify/services/vs_7hK2pQmN4rT8sX1c \
  -H 'Authorization: Bearer mk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "perMinuteCap": 30,
    "smsTemplateVariant": "short"
  }'

{
  "service": {
    "id": "vs_7hK2pQmN4rT8sX1c",
    "friendlyName": "Acme",
    "isDefault": true,
    "enabledChannels": ["email", "sms", "voice"],
    "codeLength": 6,
    "codeTtlSeconds": 600,
    "allowedCountries": ["US", "CA"],
    "perMinuteCap": 10,
    "perDayCap": 1000,
    "smsTemplateVariant": "standard",
    "emailSubject": null,
    "emailBodyHtml": null,
    "notes": null,
    "createdAt": "2026-07-25T18:04:11.000Z",
    "updatedAt": "2026-07-25T18:04:11.000Z"
  }
}

Preview a template

Renders the exact template a real send would produce for this service, using a sample code that respects the service's codeLength. This calls the same render functions the dispatcher uses, so the preview can never drift from a real message.

Query parameters

curl -X GET 'https://api.message.com/v1/verify/services/vs_7hK2pQmN4rT8sX1c/preview?channel=sms' \
  -H 'Authorization: Bearer mk_live_...'

{
  "channel": "sms",
  "text": "Your Acme verification code is 123456. It expires in 10 minutes."
}

{
  "channel": "email",
  "subject": "123456 is your Acme verification code",
  "html": "<p>Your Acme verification code is <strong>123456</strong>...</p>",
  "text": "Your Acme verification code is 123456..."
}

{
  "error": "preview_not_available",
  "channel": "whatsapp"
}

Delete a service

Deletes a non-default service. Deleting the workspace's default service returns 409 default_service (make a different service default first, then delete this one). An id that does not resolve returns 404 not_found.

curl -X DELETE https://api.message.com/v1/verify/services/vs_7hK2pQmN4rT8sX1c \
  -H 'Authorization: Bearer mk_live_...'

{ "deleted": true }

Service endpoint errors

Webhook endpoints

Webhook endpoints subscribe to Verify lifecycle events (verify.started, verify.succeeded, verify.failed) instead of polling. They live on the same dual-auth surface as services and can optionally be scoped to a single Verify Service.

Create a webhook

curl -X POST https://api.message.com/v1/verify/webhooks \
  -H 'Authorization: Bearer mk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://acme.com/webhooks/verify",
    "topics": ["verify.succeeded", "verify.failed"]
  }'

{
  "webhook": {
    "id": "uuid",
    "workspaceId": "uuid",
    "url": "https://acme.com/webhooks/verify",
    "secret": "whsec_...",
    "topics": ["verify.succeeded", "verify.failed"],
    "serviceId": null,
    "enabled": true,
    "consecutiveFailures": 0,
    "disabledReason": null,
    "createdBy": "uuid",
    "createdAt": "2026-07-25T18:04:11.000Z",
    "updatedAt": "2026-07-25T18:04:11.000Z"
  }
}

The secret field is what you use to verify the X-Webhook-Signature header on incoming deliveries; see Webhooks overview for the signing scheme. It is returned on this create response and is currently also included in the list and update responses. Treat it as a credential either way: store it server-side next to your API key, and never expose it to a browser or mobile client.

List webhooks

Optional ?serviceId=vs_...narrows to one service's endpoints. Without it, every webhook in the workspace is returned.

Update a webhook

Accepts url, topics, and enabled. Changing url re-runs the public-URL check. Setting enabled: truealso clears the endpoint's failure counter and any auto-disable reason from repeated delivery failures.

Delete a webhook

List recent deliveries

Returns the endpoint's last 50 delivery attempts, newest first.

Send a test delivery

Enqueues one synthetic delivery to this endpoint with a fixed sample payload (topic verify.test), bypassing topic matching so it always reaches this endpoint regardless of its subscribed topics. Useful for confirming your receiving server and signature verification work before relying on a real event.

curl -X POST https://api.message.com/v1/verify/webhooks/{id}/test \
  -H 'Authorization: Bearer mk_live_...'

{ "enqueued": true }

Webhook endpoint errors

Common pitfalls

• You cannot un-default a service without defaulting another. There is always exactly one default per workspace with at least one service.
• Preview only covers channels with a shipped template. Requesting a preview for whatsapp, push, totp, or sna returns 422, matching those channels' channel_not_available status on the send side.
• Webhook secrets are credentials. The secret appears in create, list, and update responses today, so any code path that logs or proxies those responses is leaking a signing key. Keep it server-side only.
• A repeatedly-failing webhook can auto-disable. If deliveries stop arriving, check enabled and disabledReason on the endpoint before assuming the server-side sender is broken.