wayou/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
• Support
• Quick Start
• Plugin
• Resources

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:

   • Perl https://github.com/getprove/prove-perl
   • Node https://github.com/getprove/prove-node
   • Ruby https://github.com/getprove/prove-ruby
   • Python https://github.com/getprove/prove-python
   • PHP https://github.com/getprove/prove-php

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 [email protected] 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

Request:

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

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