Skip to main content

Quick start guide

Here are the essential steps to integrating with Vouchsafe.

1. Get an access token​

Get your Client ID and Production secret from the API integrations page of the dashboard.

Use those secrets to create an access token:

curl -X POST "https://app.vouchsafe.id/api/v2/authenticate" \
 -H "Content-Type: application/json" \
 -d "{\"client_id\":\"string\", \"client_secret\":\"string\"}"

Or with Node.js:

fetch("https://app.vouchsafe.id/api/v2/authenticate", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: {
    client_id: "string",
    client_secret: "string",
  },
})

You’ll get a response like:

{
  "access_token": "ACCESS_TOKEN",
  "expires_at": "string" // expiration as an ISO8601 timestamp
}

An access token lasts for up to one day. We don’t yet support refresh tokens.

Once your access token expires, request a new one the same way.

2. Request a verification​

Use your access token to request verification, passing in:

  • an email
  • a workflow_id
  • optionally, a redirect_url for us to send the user back to once verification is complete. If given, this will override the default for all verifications entered on the team Settings page.
curl -X POST "https://app.vouchsafe.id/api/v1/verifications" \
 -H "accept: application/json" \
 -H "Authorization: Bearer ACCESS_TOKEN" \
 -d "{\"email\":\"string\", \"workflow_id\":\"string\", \"redirect_url\":\"string\"}"

You’ll get a response like:

{
  "url": "string",
  "id": "string",
  "expires_at": "string" // expiration as an ISO8601 timestamp
}

3. Send the user for verification​

Send the user to the URL returned.

We recommend redirecting the page, but it’s possible to open the URL in:

  • a native app’s web view
  • an iframe.

4. Check verification results​

Use the ID from step 2 to see the status of the case and the checks that have been conducted:

curl -X GET "https://app.vouchsafe.id/api/v2/verifications/<ID>" \
 -H "accept: application/json" \
 -H "Authorization: Bearer ACCESS_TOKEN"

You’ll get a response like:

{
  "id": "string",
  "email": "string",
  "redirect_url": "string",
  "status": "InProgress",
  "created_at": "string",
  "expires_at": "string",
  "workflow_id": "string",
  "external_id": "string"
}

The best time to do this is either:

  • once the user returns to the redirect URL you specified (see step 2)
  • after you get a webhook notification (see step 5)

5. Stay informed with webhooks​

Provide a webhook URL in a verification flow's setting to get immediate messages when a verification completes.

Vouchsafe will make POST requests to that URL.

See the full list of supported events.