/prove-api

Prove API documentation.

Docs

Prove is a phone verification service that allows you to utilize our API to verify your users.

Users receive an SMS or phone call and verify their phone number with pin.

Index

Overview

  1. Sign up for a free Prove developer account.

  2. Grab your API test and live keys from your dashboard.

  3. Integrate with one of our RESTful API wrappers:

See Quick Start or Plugin for example implementations.

Support

Send us a tweet @getprove.

Join us on IRC WebChat or with a client in #getprove on irc.freenode.net.

You can also email support@getprove.com or file an Issue.

Quick Start

  1. Send us a phone number to verify by text message ("SMS").

    Request:

    curl https://getprove.com/api/v1/verify \
     -u YOUR-SECRET-API-KEY: \
     -d tel=1234567890

    Response:

    {
  "id": "518c4db62602b8fe02000061",
  "tel": "1234567890",
  "text": true,
  "call": false,
  "verified": false
}

  2. User receives SMS (text message) with a 6-digit pin. If you're in testMode, then the pin is always 000000.

  3. Send us the user entered pin to verify their phone number.

    Request:

    curl https://getprove.com/api/v1/verify/518c4db62602b8fe02000061/pin \
     -u YOUR-SECRET-API-KEY: \
     -d pin=000000

    Response:

    {
  "id": "518c4db62602b8fe02000061",
  "tel": "1234567890",
  "text": true,
  "call": false,
  "verified": true
}

Plugin

Integrate our plugin within minutes. Here's a quick example:

./public/index.html

<form action="/verify" method="post">
  <script src="//getprove.com/v1/verify.js" data-callback="/verified.html" data-key="YOUR-API-PUBLIC-KEY" class="prove-verify"></script>
</form>

./public/verified.html

<h1>Congrats, you successfully verified your phone number</h1>

./app.js

var getprove = require('getprove')('YOUR-API-SECRET-KEY')
  , path     = require('path')
  , express  = require('express')
  , app      = express()

// serve up index.html file with the plugin rendered
app.use(express.static(path.join(__dirname, 'public')))

// send responses for plugin's xhr requests
app.post('/verify', function(req, res, next) {
  getprove.verify.pin(req.body.proveToken, req.body.provePin, function(err, verify) {
    if (err) return res.send(400, err.response)
    // note: here's a good spot to store verify.id to db
    res.send(200)
  })
})

// start the server
app.listen(3000)

Then visit http://localhost:3000/ and test it out.

Resources v1

Prefix all paths with /api/v1 (e.g. /verify becomes /api/v1/verify)

Note: All created and updated fields are in ISO 8601 format as per ECMAScript 5 standard .toISOString() function.

Verify

Path Method Description
/verify GET List all verifications
/verify POST Create a new verification
/verify/:id/pin POST Verify a pin
/verify/:id GET Retrieve existing verification
/verify/:id/delete POST Delete an existing verification

List all verifications

Request:

curl https://getprove.com/api/v1/verify
  -u YOUR-SECRET-API-KEY:

Response:

[
  {
    "tel": "1234567890",
    "updated": "2013-05-10T01:30:30.962Z",
    "created": "2013-05-10T01:30:30.518Z",
    "test": true,
    "verified": true,
    "call": false,
    "text": true,
    "id": "518c4db62602b8fe02000061"
  },
  {
    "tel": "1234567890",
    "updated": "2013-05-10T01:30:30.607Z",
    "created": "2013-05-10T01:30:30.606Z",
    "test": true,
    "verified": false,
    "call": false,
    "text": true,
    "id": "518c4db62602b8fe02000062"
  },
  {
    "tel": "1234567890",
    "updated": "2013-05-10T01:30:31.251Z",
    "created": "2013-05-10T01:30:30.783Z",
    "test": true,
    "verified": true,
    "call": false,
    "text": true,
    "id": "518c4db62602b8fe02000063"
  }
]

Create a new verification

If you would like to give the user a call (Voice) instead of a text message (SMS) → please specify type: "text" or type: "call" in your request body.

Request:

curl https://getprove.com/api/v1/verify \
     -u YOUR-SECRET-API-KEY: \
     -d tel=1234567890
     -d type=text

Response:

{
  "id": "518c4e762602b8fe02000061",
  "tel": "1234567890",
  "country": "US",
  "text": true,
  "call": false,
  "test": true,
  "verified": false,
  "created": "2013-05-10T01:33:42.202Z",
  "updated": "2013-05-10T01:33:42.203Z"
}

Verify a pin

Request:

curl https://getprove.com/api/v1/verify/518c4db62602b8fe02000061/pin \
     -u YOUR-SECRET-API-KEY: \
     -d pin=000000

Response:

{
  "id": "518c4db62602b8fe02000061",
  "tel": "1234567890",
  "text": true,
  "call": false,
  "verified": true
}

Retrieve existing verification

Request:

curl https://getprove.com/api/v1/verify/518c4db62602b8fe02000061 \
     -u YOUR-SECRET-API-KEY:

Response:

{
  "id": "518c4db62602b8fe02000061",
  "tel": "1234567890",
  "text": true,
  "call": false,
  "verified": true,
  "created": "2013-05-10T01:30:30.518Z",
  "updated": "2013-05-10T01:30:30.962Z"
}

Delete existing verification

Request:

curl https://getprove.com/api/v1/verify/518c4db62602b8fe02000061/delete \
     -u YOUR-SECRET-API-KEY:

Response:

{
  "id": "518c4db62602b8fe02000061",
  "tel": "1234567890",
  "text": true,
  "call": false,
  "verified": true,
  "created": "2013-05-10T01:30:30.518Z",
  "updated": "2013-05-10T01:30:30.962Z"
}