You can take advantage of IO Phone programmatically through our API version 6 and above.
Base URL: https://rental.software/api6
Required query parameters: apiKey
POST /text
Request Body Parameters
- toNumber string required
- The phone number the message should be sent to
- E.164 format is recommended but not required
- text string required
- The contents of the text message
- Must be 2048 characters or less
- fromNumber string
- One of your IO Phone numbers that the message should be sent from
- E.164 format is recommended but not required
- If omitted, an IO Phone number of yours will be chosen automatically
- callbackUrl string
- The URL where webhook requests will be sent
- http or https is required; https (TLS) is highly recommended
- The most recent callback URL that you’ve sent is stored on our server (one per fromNumber)
- If omitted, the most recent callback URL associated with fromNumber will be used
- The callback URL can be cleared from our server by sending it to us as an empty string ("")
- If a callback URL has never been specified or was cleared for a given fromNumber, webhooks will not be sent
- country string default "US"
- Optional country code with which to force toNumber to be parsed, in ISO 3166-1 alpha-2 format
- It’s recommended to only specify this parameter if toNumber’s country of origin is known and its format is nonstandard or unknown
Response Schema
Blue indicates properties that are only sent when the message is accepted
Red indicates properties that are only sent when the message fails
- id integer
- The unique ID associated with the message
- time string
- The UTC timestamp of the message, in ISO 8601 format
- segmentCount integer
- The number of segments that the message was broken into before sending over to carrier networks
- direction string
- The direction of the message, either in or out
- to string
- The phone number the message was sent to, in E.164 format
- from string
- The phone number the message was sent from, in E.164 format
- text string
- The text message content that was sent to the recipient
- status integer
- The status code associated with the request
- If the message was accepted, 202 should be expected
- Errors will return a status code >= 400 and <= 599
- message string
- A message describing the error
Example Request
POST https://rental.software/api6/text?apiKey=XXXX
Content-Type: application/json { "toNumber": "+15554447777", "fromNumber": "+15551112222", "text": "Hello world", "callbackUrl": "https://my-callback-url/path" }
Example Responses
Successful response example
200 OK Content-Type: application/json { "id": 1753065, "time": "2023-09-14T17:28:18.709287Z", "segmentCount": 1, "direction": "out", "to": "+15554447777", "from": "+15551112222", "text": "Hello world", "status": 202, "request_time": 1694712498 }
Error response examples
400 Bad Request Content-Type: application/json { "status": 400, "message": "Required parameter 'text' cannot be empty" }
403 Forbidden Content-Type: application/json { "status": 403, "message": "This account is not authorized to send text messages from this number ('fromNumber')" }
Webhook Response Examples
POST {YOUR_CALLBACK_URL}
Content-Type: application/json
Outbound message delivery receipt
{ "id": 1753064, "time": "2023-09-14T15:59:38.406172698Z", "type": "message-delivered", "description": "Message delivered to carrier.", "segmentCount": 1, "direction": "out", "to": "+15554447777", "from": "+15551112222" }
Inbound message received
{ "id": 1753060, "time": "2023-09-14T13:52:27.881412Z", "type": "message-received", "description": "Incoming message received", "segmentCount": 1, "direction": "in", "to": "+15551112222", "from": "+15554447777", "text": "Hello world" }
Outbound message failure
{ "id": 1753063, "time": "2023-09-14T17:56:57.406573455Z", "type": "message-failed", "description": "invalid-destination-address", "segmentCount": 0, "direction": "out", "to": "+15554447777", "from": "+15551112222", "errorCode": 4720 }
Testing
You can test sending through the API by using a from Number of (999) 999-9999. Test SMS messages are not sent but we simulate as if they are and will also initiate a send to your call back URL if you have specified one. See the example send and call back below.
Send
{ "id": 5553, "time": "2023-09-18T15:49:43.052Z", "segmentCount": 1, "direction": "out", "to": "+16142579242", "from": "+19999999999", "text": "API Test Request", "status": 202, "request_time": 1695066583 }Call Back
{ "id": 5553, "time": "2023-09-18T15:49:43.052Z", "type": "message-delivered", "description": "Message delivered to carrier.", "segmentCount": 1, "direction": "out", "to": "+16142579242", "from": "+19999999999" }