generated: '2026-07-21'
method: searched
source: >-
  https://docs.unifonic.com/articles/api-documentation/getting-started plus the
  Security & Authentication, HTTP Status Codes, and Base URL pages, and the
  three official OpenAPI documents in this repo's openapi/ directory.
description: >-
  Cross-cutting request/response semantics of Unifonic's public APIs — the
  runtime behaviors OpenAPI does not fully express. Unifonic's surface is
  split across product hosts (el.cloud.unifonic.com for SMS NextGen,
  authenticate.cloud.api.unifonic.com for OTP, voice.unifonic.com for Voice),
  authenticated with an AppSid/AppsId application credential, JSON-only
  responses, and an extended HTTP-style status-code vocabulary for errors.
api_style: REST over HTTPS; SMS API takes query/form parameters, Authenticate takes application/x-www-form-urlencoded bodies, Voice takes JSON bodies; responses are JSON only

hosts:
  - {product: SMS (NextGen), base_url: 'https://el.cloud.unifonic.com', paths: '/rest/SMS/*, /wrapper/* (legacy)'}
  - {product: Authenticate (OTP), base_url: 'https://authenticate.cloud.api.unifonic.com', paths: '/services/api/v2/verifications/*'}
  - {product: Voice, base_url: 'https://voice.unifonic.com/v1', paths: '/calls, /providers/*'}

authentication:
  scheme: AppSid application credential (see authentication/unifonic-authentication.yml)
  notes:
    - SMS API declares HTTP basic auth globally and requires an AppSid query parameter on every operation; error 459 covers incorrectly base64-encoded auth parameters.
    - Authenticate API uses x-authenticate-app-id + Authorization (bearer token) headers.
    - Voice API uses a custom AppsId credential from the Console's Voice Applications tab.
  detail: authentication/unifonic-authentication.yml

versioning:
  scheme: URL-path per product (no version-pinning header)
  examples: [/services/api/v2 (Authenticate), /v1 (Voice), /rest (SMS NextGen)]
  change_communication: monthly dated release notes (see changelog/unifonic-changelog.yml)

idempotency:
  documented_contract: false
  notes: >-
    No Idempotency-Key header or documented idempotency contract exists in the
    published specs or docs. The SMS API does expose a CorrelationID parameter
    ("a unique identifier value that is attached to requests and messages")
    and returns status 409 "This message is duplicate" and 456 "Wrong
    correlationId format", which together provide message-level duplicate
    detection, but Unifonic does not document replay-safe idempotency
    semantics for it.

request_tracing:
  parameter: CorrelationID
  location: query (SMS API)
  purpose: unique identifier attached to requests and messages; also drives duplicate detection (409)

pagination:
  style: limit + date-window filtering (SMS message queries)
  params: [Limit, dateFrom, dateTo, MessageID]
  notes: Error 420 "Page limit Exceeds" signals paging limits on message-detail queries. No cursor pagination is documented.

encoding:
  message_body: GSM7 or UCS2 (error 460 "Invalid encoding (Should be UCS2 or GSM7)")
  request_flag: baseEncode query parameter (binary-to-text encoding of parameter values)
  response_format: JSON only (responseFormat/responseType parameters accept json only)

error_envelope:
  sms_rest: '{ "success": "true|false", "message": "...", "errorCode": "ER-XX", "data": { } }'
  authenticate: '{ "id", "response_status": "correct|incorrect", "error_code": 101|107|108|109|110 }'
  status_codes: extended HTTP-style vocabulary (400-599, many Unifonic-specific, e.g. 455, 480, 599)
  detail: errors/unifonic-problem-types.yml

rate_limit_signaling:
  status: 429 Too many requests generated by this user
  headers: none documented

webhooks:
  callbacks:
    - statusCallback parameter on SMS Sendmessage (delivery status callback URL)
    - POST /providers/webhook on the Voice API (createsWebhook) registers a webhook for call statuses
  docs: https://docs.unifonic.com/articles/api-documentation/setting-up-a-webhook-to-receive-call-statuses

scheduling:
  params: [TimeScheduled]
  format: 'yyyy-mm-dd HH:mm:ss (must be in the future — error 451)'

cross_links:
  errors: errors/unifonic-problem-types.yml
  authentication: authentication/unifonic-authentication.yml
  lifecycle: lifecycle/unifonic-lifecycle.yml
  changelog: changelog/unifonic-changelog.yml