Skip to content

API 3.2

API 3.2 modernises the public routes and provides generated OpenAPI and Scalar documentation alongside the narrative guides.

Reference documentation

API 3.2 uses the following versioned route prefix:

/v3.2/

All requests must use HTTPS.

Note

The generated specification currently advertises the server using http. Replace it with https in generated examples. Authentication remains mandatory; see Security because the generated document does not currently expose an interactive authentication scheme.

Warning

Do not redirect production traffic until DIY Surveys confirms the production endpoint and migration date.

Breaking route changes

API 3.2 removes the /api segment from the version prefix and adopts REST-style resource routes. Existing clients must update their URLs and, for number lookup, the request method and parameter location.

Capability API 3.1 API 3.2
Send a message POST /api/v3.1/Message/Send POST /v3.2/Message
Look up a number GET or POST /api/v3.1/Message/Lookup GET /v3.2/Message/Lookup/{number}
Kill a message DELETE /api/v3.1/Message/Kill Not exposed in API 3.2
Add a keyword POST /api/v3.1/Keyword/Add POST /v3.2/Keyword
Update a keyword Not exposed PATCH /v3.2/Keyword
Delete a keyword DELETE /api/v3.1/Keyword/Delete DELETE /v3.2/Keyword?keyword={keyword}
List keywords GET /api/v3.1/Keyword/List GET /v3.2/Keyword
List webhooks GET /api/v3.1/Webhook/List GET /v3.2/Webhook

The Data Import, Survey GetResults, and TinyUrl operations retain their resource suffixes but use the new /v3.2 prefix.

Operations

Method Route Purpose
POST /v3.2/Data/Import Import data using a survey custom-import definition.
POST /v3.2/Keyword Add a keyword.
PATCH /v3.2/Keyword Update a keyword.
DELETE /v3.2/Keyword?keyword={keyword} Delete a keyword.
GET /v3.2/Keyword List registered keywords.
GET /v3.2/Message/Lookup/{number} Check number reachability, carrier, and number type.
POST /v3.2/Message Send a message.
POST /v3.2/Survey/GetResults Collect survey results.
POST /v3.2/TinyUrl/Register Register one URL.
POST /v3.2/TinyUrl/RegisterList Register multiple URLs.
GET /v3.2/Webhook List webhooks for the authenticated user.

Migration checklist

  1. Change the base path from /api/v3.1/ to /v3.2/.
  2. Replace action-based messaging, keyword, and webhook routes using the table above.
  3. Change number lookup to HTTP GET and place the E.164 number in the URL path.
  4. Remove dependencies on the message-kill operation from API 3.2 clients.
  5. Validate request and response models against the Scalar reference.
  6. Test the complete integration against the allocated API 3.2 endpoint before production migration.