Back to top

Promptxt API

The API allows a third party to send SMS messages and to retrieve reporting information. This document is intended for those parties who wish to develop applications that make use of the API.

Authentication

To use the API you must obtain an access token and include it as part of the headers for each request. This token identifies you as a valid user of the service. The API implements the standardized OAuth 2.0 bearer token specification already supported by many HTTP clients.

Autorization: Bearer <token>

API tokens can be generated from the /auth/login endpoint.

Tokens have a lifespan of 24 hours and should be renewed daily to maintain continuous access.

User

User login

Login
POST/auth/login

Example URI

POST https://api.promptxt.com/auth/login
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "username": "smith123",
  "password": "######"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "username": {
      "type": "string"
    },
    "password": {
      "type": "string"
    }
  },
  "required": [
    "username",
    "password"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "token": "<token>"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "token": {
      "type": "string"
    }
  }
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "status": 400,
    "reason": "Invalid username or password"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "status": {
          "type": "number"
        },
        "reason": {
          "type": "string",
          "description": "check username or password"
        }
      }
    }
  }
}

User profile

Profile
GET/users/me

Example URI

GET https://api.promptxt.com/users/me
Request
HideShow
Headers
Authorization: Bearer <token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "user": {
    "id": 12345678,
    "username": "smith123",
    "timezone": "America/New_York"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "user": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number"
        },
        "username": {
          "type": "string"
        },
        "timezone": {
          "type": "string"
        }
      }
    }
  }
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "status": 401,
    "reason": "Unauthorized"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "status": {
          "type": "number"
        },
        "reason": {
          "type": "string",
          "description": "Invalid access token"
        }
      }
    }
  }
}

Send SMS

Send message

Send message
POST/sendsms

Example URI

POST https://api.promptxt.com/sendsms
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <token>
Body
{
  "text": "Test message",
  "number": "12345678901",
  "senderMsgId": "Custom reference"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "text": {
      "type": "string"
    },
    "number": {
      "type": "string"
    },
    "senderMsgId": {
      "type": "string"
    }
  },
  "required": [
    "text",
    "number"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "message": {
    "id": "36889592",
    "text": "Test message",
    "number": "12345678901",
    "senderMsgId": "Custom reference"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "message": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "text": {
          "type": "string"
        },
        "number": {
          "type": "string"
        },
        "senderMsgId": {
          "type": "string"
        }
      }
    }
  }
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "status": 400,
    "reason": "Bad request"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "status": {
          "type": "number"
        },
        "reason": {
          "type": "string",
          "description": "check request data format"
        }
      }
    }
  }
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "status": 401,
    "reason": "Unauthorized"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "status": {
          "type": "number"
        },
        "reason": {
          "type": "string",
          "description": "Invalid access token"
        }
      }
    }
  }
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "status": 404,
    "reason": "Not found"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "status": {
          "type": "number"
        },
        "reason": {
          "type": "string",
          "description": "The resource was not found"
        }
      }
    }
  }
}

Sent messages

Sent messages today

Today
GET/messages

Example URI

GET https://api.promptxt.com/messages
Request
HideShow
Headers
Authorization: Bearer <token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "messages": [
    {
      "id": "36889592",
      "text": "Test message",
      "number": "12345678901",
      "senderMsgId": "Custom reference"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "messages": {
      "type": "array"
    }
  }
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "status": 401,
    "reason": "Unauthorized"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "status": {
          "type": "number"
        },
        "reason": {
          "type": "string",
          "description": "Invalid access token"
        }
      }
    }
  }
}

Sent messages by day

Day
GET/messages/day/{date}

Example URI

GET https://api.promptxt.com/messages/day/2018-10-10
URI Parameters
HideShow
date
string (required) Example: 2018-10-10

Date of day to query

Request
HideShow
Headers
Authorization: Bearer <token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "messages": [
    {
      "id": "36889592",
      "text": "Test message",
      "number": "12345678901",
      "senderMsgId": "Custom reference"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "messages": {
      "type": "array"
    }
  }
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "status": 400,
    "reason": "Bad request"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "status": {
          "type": "number"
        },
        "reason": {
          "type": "string",
          "description": "check request data format"
        }
      }
    }
  }
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "status": 401,
    "reason": "Unauthorized"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "status": {
          "type": "number"
        },
        "reason": {
          "type": "string",
          "description": "Invalid access token"
        }
      }
    }
  }
}

Sent messages by month

Month
GET/messages/month/{date}

Example URI

GET https://api.promptxt.com/messages/month/2018-10
URI Parameters
HideShow
date
string (required) Example: 2018-10

Date of month to query

Request
HideShow
Headers
Authorization: Bearer <token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "messages": [
    {
      "id": "36889592",
      "text": "Test message",
      "number": "12345678901",
      "senderMsgId": "Custom reference"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "messages": {
      "type": "array"
    }
  }
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "status": 400,
    "reason": "Bad request"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "status": {
          "type": "number"
        },
        "reason": {
          "type": "string",
          "description": "check request data format"
        }
      }
    }
  }
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "status": 401,
    "reason": "Unauthorized"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "status": {
          "type": "number"
        },
        "reason": {
          "type": "string",
          "description": "Invalid access token"
        }
      }
    }
  }
}

Sent message

Message
GET/messages/{id}

Example URI

GET https://api.promptxt.com/messages/36889592
URI Parameters
HideShow
id
string (required) Example: 36889592

Message identifier

Request
HideShow
Headers
Authorization: Bearer <token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "message": {
    "id": "36889592",
    "text": "Test message",
    "number": "12345678901",
    "senderMsgId": "Custom reference"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "message": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "text": {
          "type": "string"
        },
        "number": {
          "type": "string"
        },
        "senderMsgId": {
          "type": "string"
        }
      }
    }
  }
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "status": 400,
    "reason": "Bad request"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "status": {
          "type": "number"
        },
        "reason": {
          "type": "string",
          "description": "check request data format"
        }
      }
    }
  }
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "status": 401,
    "reason": "Unauthorized"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "status": {
          "type": "number"
        },
        "reason": {
          "type": "string",
          "description": "Invalid access token"
        }
      }
    }
  }
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "status": 404,
    "reason": "Not found"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "status": {
          "type": "number"
        },
        "reason": {
          "type": "string",
          "description": "The resource was not found"
        }
      }
    }
  }
}

Inbox messages

Received messages today

Today
GET/inbox

Example URI

GET https://api.promptxt.com/inbox
Request
HideShow
Headers
Authorization: Bearer <token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "messages": [
    {
      "id": "36889592",
      "text": "Test message",
      "number": "12345678901"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "messages": {
      "type": "array"
    }
  }
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "status": 401,
    "reason": "Unauthorized"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "status": {
          "type": "number"
        },
        "reason": {
          "type": "string",
          "description": "Invalid access token"
        }
      }
    }
  }
}

Received messages by day

Day
GET/inbox/day/{date}

Example URI

GET https://api.promptxt.com/inbox/day/2018-10-10
URI Parameters
HideShow
date
string (required) Example: 2018-10-10

Date of day to query

Request
HideShow
Headers
Authorization: Bearer <token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "messages": [
    {
      "id": "36889592",
      "text": "Test message",
      "number": "12345678901"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "messages": {
      "type": "array"
    }
  }
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "status": 400,
    "reason": "Bad request"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "status": {
          "type": "number"
        },
        "reason": {
          "type": "string",
          "description": "check request data format"
        }
      }
    }
  }
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "status": 401,
    "reason": "Unauthorized"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "status": {
          "type": "number"
        },
        "reason": {
          "type": "string",
          "description": "Invalid access token"
        }
      }
    }
  }
}

Received messages by month

Month
GET/inbox/month/{date}

Example URI

GET https://api.promptxt.com/inbox/month/2018-10
URI Parameters
HideShow
date
string (required) Example: 2018-10

Date of month to query

Request
HideShow
Headers
Authorization: Bearer <token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "messages": [
    {
      "id": "36889592",
      "text": "Test message",
      "number": "12345678901"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "messages": {
      "type": "array"
    }
  }
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "status": 400,
    "reason": "Bad request"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "status": {
          "type": "number"
        },
        "reason": {
          "type": "string",
          "description": "check request data format"
        }
      }
    }
  }
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "status": 401,
    "reason": "Unauthorized"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "status": {
          "type": "number"
        },
        "reason": {
          "type": "string",
          "description": "Invalid access token"
        }
      }
    }
  }
}

Received message

Message
GET/inbox/{id}

Example URI

GET https://api.promptxt.com/inbox/123456
URI Parameters
HideShow
id
string (required) Example: 123456

Message identifier

Request
HideShow
Headers
Authorization: Bearer <token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "message": {
    "id": "36889592",
    "text": "Test message",
    "number": "12345678901"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "message": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "text": {
          "type": "string"
        },
        "number": {
          "type": "string"
        }
      }
    }
  }
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "status": 400,
    "reason": "Bad request"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "status": {
          "type": "number"
        },
        "reason": {
          "type": "string",
          "description": "check request data format"
        }
      }
    }
  }
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "status": 401,
    "reason": "Unauthorized"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "status": {
          "type": "number"
        },
        "reason": {
          "type": "string",
          "description": "Invalid access token"
        }
      }
    }
  }
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "status": 404,
    "reason": "Not found"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "status": {
          "type": "number"
        },
        "reason": {
          "type": "string",
          "description": "The resource was not found"
        }
      }
    }
  }
}

Subscribers

Subscribers that have opted-out of receiving further communications.

Optouts

Get numbers
GET/optouts

Example URI

GET https://api.promptxt.com/optouts
Request
HideShow
Headers
Authorization: Bearer <token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "numbers": [
    "12345678901",
    "12345678902",
    "12345678903"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "numbers": {
      "type": "array"
    }
  }
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "status": 401,
    "reason": "Unauthorized"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "status": {
          "type": "number"
        },
        "reason": {
          "type": "string",
          "description": "Invalid access token"
        }
      }
    }
  }
}

Add number
POST/optouts

Example URI

POST https://api.promptxt.com/optouts
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <token>
Body
{
  "number": "12345678901"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "number": {
      "type": "string",
      "description": "Number to add to optout list"
    }
  },
  "required": [
    "number"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "number": "12345678901"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "number": {
      "type": "string"
    }
  }
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "status": 400,
    "reason": "Bad request"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "status": {
          "type": "number"
        },
        "reason": {
          "type": "string",
          "description": "check request data format"
        }
      }
    }
  }
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "status": 401,
    "reason": "Unauthorized"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "status": {
          "type": "number"
        },
        "reason": {
          "type": "string",
          "description": "Invalid access token"
        }
      }
    }
  }
}

Generated by aglio on 11 Nov 2018