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
}

{
    "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"
}