Quick start guide | Vouchsafe Help Centre

📽️ We also have a three-minute video guide showing how to use the API.

1. Get an access token

Get your Client ID and Live 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

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.

What next? See what else you can do with the API with the full reference, or try an SDK or library.

How to set up webhooks

Set up Vouchsafe as a partner or reseller