Skip to main content
Find quick answers to common integration questions. For complete request and response schemas, use the API Reference.

​
Authentication

Send either a Phonovation Personal Access Token (PAT) or an OAuth access token in the Authorization header:
See Authentication for setup guidance.
Yes. PATs beginning with phv_pat_ can authenticate campaign requests. Generate the token once, store it securely, and reuse it until it expires or is revoked.
The API returns 401 when authentication is missing or unsuccessful. The token may be missing, invalid, expired, or revoked.The response can have an empty body and include:
The API returns 403 when the token is valid but does not resolve to a recognized Phonovation client administrator.
No. PAT-management operations reject PAT authentication. Use an OAuth-authenticated application session to manage PATs.
Use a PAT for most server-to-server integrations. Use OAuth when your integration specifically needs an access-token and refresh-token lifecycle.

​
Creating campaigns

Send an authenticated JSON request to:
A campaign can contain:
  • text, from, and recipientInfo
  • an optional campaignName
  • an optional Irish-local sendAt value
  • optional createAsDraft and shouldSaveList flags
  • an optional ClientReference for each recipient
Review the create campaign reference for the complete schema.
text, from, and recipientInfo are required. Every recipient must have a valid msisdn, and the request must contain at least one recipient.
It defaults to API Broadcast. If you explicitly supply null, an empty string, or whitespace, validation fails.
text can contain up to 2,000 characters. It cannot be null, empty, or whitespace-only. Message encoding can affect the number of SMS parts sent and billed; use the SMS Message Lab to inspect it.
Numeric Sender IDs can contain up to 20 digits. Other Sender IDs can contain up to 11 characters. Irish alphanumeric Sender IDs also follow ComReg registration rules. See Sender IDs.
Yes, when using an alphanumeric Sender ID to deliver SMS to Irish mobile numbers. An Irish recipient whose Sender ID is not permitted can be skipped. Register the Sender ID with ComReg, select Phonovation as its OPA, and ask Phonovation Support to assign it to your account.
Use the full international number as digits only, without a leading +, spaces, brackets, or hyphens. A submitted msisdn can contain up to 20 characters and must pass the API’s parsing and normalization rules.
ClientReference is an optional reference associated with one recipient. It can contain up to 30 characters and is returned unchanged in the delivery webhook, allowing you to match the receipt with your own customer, order, or appointment.It does not need to be unique. See Client Reference.
sendAt is always interpreted as Irish local time in Europe/Dublin. Prefer yyyy-MM-ddTHH:mm, for example:
A space instead of T and optional seconds are also accepted. Supplied seconds are ignored. Do not include Z or a numeric timezone offset. See Sending SMS for international conversion examples.
Omit sendAt or send null to send immediately. Empty and whitespace-only strings are invalid.
The application does not publish a maximum recipient count. Hosting infrastructure may still impose request-size limits.
Invalid recipients are skipped during parsing. Campaign creation can continue if at least one valid recipient remains. The request fails with 400 Bad Request if no valid recipient remains.
Duplicate detection runs after phone-number normalization. The first occurrence and its ClientReference are kept. If no valid unique recipient remains, campaign creation fails with 400 Bad Request.
They are removed before the campaign is created. If no permitted recipient remains, the API returns 400 Bad Request.
The API returns 400 Bad Request with a validation response:

​
Campaign responses and status

A campaign accepted for background processing returns 202 Accepted:
A 202 confirms that the command was queued. It does not confirm that processing or handset delivery succeeded.
The detail value depends on the validation or campaign-creation failure.
The public contract documents 202 Accepted, 400 Bad Request, 401 Unauthorized, and 403 Forbidden.
Use the UUID returned by the create response:
All four properties are integers.
No. The lookup uses both the supplied campaign UUID and the authenticated account. A campaign belonging to another account is not returned.
The API returns 404 Not Found. The campaign may be unknown, belong to another account, still be processing, or not yet have a summary.

​
Delivery webhooks

Phonovation sends a delivery webhook when a delivery receipt is created and your account has an enabled webhook configuration.
Phonovation sends JSON with an HTTP POST to the webhook URL configured in your developer settings.
The documented property names use To, From, Status, and ClientReference.
The webhook still contains ClientReference, with a value of null.
Yes. The value submitted for a recipient is stored with that campaign recipient and returned in the webhook as ClientReference.
Confirmed examples include DELIVRD, DELIVERED, DELIV, UNDELIV, REJECTD, EXPIRED, ABANDONED, and FAILED.This is not a closed list. Treat Status as an open-ended string because raw provider status text can be returned when a normalized value cannot be extracted.
No. Confirmed delivered forms include DELIVRD, DELIVERED, and DELIV. The current implementation treats statuses beginning with DELIV as delivered.
Yes. Examples include NACK/ and NACK/0x000000ff/Unknown Error. Do not restrict Status to a fixed enum.

​
Webhook signatures and retries

When a webhook secret is configured, the request includes:
Phonovation serializes the JSON payload, encodes that exact body as UTF-8, calculates an HMAC-SHA256 digest using the webhook secret, converts the result to lowercase hexadecimal, and prefixes it with sha256=.
Verify the signature against the exact raw HTTP request-body bytes you received. Do not parse and rebuild the JSON before calculating the signature because whitespace or property-order changes produce a different HMAC.
The header is omitted when no webhook secret is configured. Configure both a webhook URL and signing secret before enabling delivery.
Return any successful 2xx status after you have safely stored or queued the event. The full 200–299 range is accepted.
Yes. Phonovation retries network failures, 404 Not Found, 408 Request Timeout, and 5xx responses. It configures three retries after approximately 2, 4, and 8 seconds.A circuit breaker opens for 30 seconds after two transient failures. While open, it can prevent configured retries from becoming actual HTTP requests.
No. Ordinary 4xx responses such as 400 Bad Request, 401 Unauthorized, and 403 Forbidden are not retried.
Yes. A request may be processed even when Phonovation cannot receive the response, causing a retry. Make the handler idempotent so processing a duplicate does not repeat a business action or corrupt status.
No ordering guarantee is published. Do not depend on delivery receipts arriving in a particular order.
Need another answer? Email support@phonovation.com.