Introduction to SuperPhone’s API

Aug 23, 2019 · 4 min read


SuperPhone’s API allows you to build a fully custom SMS marketing system in the easiest way imaginable. You won’t need to worry about all the regulations that make building a scalable SMS ecosystem so hard to do — SuperPhone handles all of this already.

SuperPhone’s API uses an API key for authentication and GraphQL as the base. In this tutorial we’ll show you how to use the API and how you can do simple REST POST requests you’re familiar to retrieve data from SuperPhone.


We constantly add features to our Public API with the goal of offering everything that’s on our private API on the Public API. So there might be more features available than we have listed here. For everything available please read our documentation. We also make sure to add every feature in a user friendly way to our Zapier integration.

As of this writing our API allows for:

  • Retrieving information about a single contact
  • Retrieving a list of contacts (as shown in this tutorial)
  • Retrieving a contact by their email or phone number
  • Retrieving all messages in a conversation
  • Retrieving a list of conversations
  • Retrieving the current configuration of your default form
  • Retrieving the current configuration of any form
  • Retrieving a list of forms
  • Retrieving a list of webhooks linked to your account
  • Creation of contacts
  • Updating contacts
  • Adding custom contributions
  • Updating a custom contribution
  • Removing a custom contribution
  • Adding tags to contacts, either by tag name or tag ID
  • Removing tags from a contact, either by tag name or tag ID
  • Sending a message (as shown in this tutorial)
  • Creating a form
  • Updating a form
  • Disabling a form
  • Enabling a form
  • Creating Webhooks for:
  • Contact added events
  • Contact updated events
  • Contact tags changed events
  • Message received events
  • Message sent events
  • Updating a Webhook

The API Key

The API key can be found on the settings page of your SuperPhone account, towards the bottom. Here’s a direct link:

When you first get started you need to generate an API key. You can always come back here to revoke or regenerate it. You’ll also find a link to our documentation on this page. In order to copy the API key, just click the copy icon next to it:

Image for post
Image for post

API Explorer

Before implementing the API into your system, you can use our API explorer to test API calls you’ll eventually want to use. The explorer can be found here:

To get started, paste the API key at the top:

Image for post
Image for post

Now we’re ready to write some requests. In GraphQL searches are called queries and actions are called mutations. To find our more about GraphQL, feel free to check out the numerous articles online, like this one:

We’ll start by writing a request to get the latest 10 contacts:

query getContacts {
contacts(last: 10) {
nodes {
tags(first: 10) {
nodes {

Tip: Pressing ctrl + space will present you with the options you have throughout the explorer.

Let’s run the query and see what happens:

Image for post
Image for post

Great — this worked! Now let’s send our first message to me, the writer of this article to let me know you’re trying out the API:

mutation sendMessage {
sendMessage(input: {
mobile: "213–267–9977",
platform: TWILIO,
body: "Hey Flo, I'm testing the API!"
}) {
message {
sendMessageUserErrors {

Note: ideally you always send the phone number in E.164 format, including the country code. For example: +12132679977. If you don’t use this format, SuperPhone will try to detect the format you’re sending and if there’s no country code, it will default to US. So if you’re texting internationally, it’s best to use E.164.

Let’s run the mutation and see what happens:

Image for post
Image for post

Great, I’ve just received your text (or whoever you texted 🙂)

Sending GraphQL requests in a REST POST request

We get this question all the time — How do I actually go ahead and send implement this? While there’s a lot of frameworks out there, and probably one that fits your system, there’s also the common way of using simple REST POST requests. Here’s how that works in Postman:

First, pick POST at the top left, set the endpoint to and then setup the headers:

Accept: application/jsonContent-Type: application/jsonAuthorization: Bearer <API Key>

It should look like this:

Image for post
Image for post

Finally we setup the body as Raw JSON like this:

Image for post
Image for post

And that’s it — Now you can run the query as a regular POST request.

If there’s something I can help you with or you are missing feature, please don’t hesitate to shoot me a text on my SuperPhone at +1 (213)-267–9977 or at!

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch

Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore

Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store