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": "ACCESS_TOKEN",
  "expiresAt": "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
  • optionally, a redirectUrl 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/v2/verifications" \
 -H "accept: application/json" \
 -H "Authorization: Bearer ACCESS_TOKEN" \
 -d "{\"email\":\"string\", \"redirectUrl\":\"string\"}"

You’ll get a response like:

{
  "url": "string",
  "id": "string",
  "expiresAt": "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",
  "status": "InProgress",
  "verificationMethod": "Document",
  "createdAt": "string",
  "email": "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 your team’s Settings page to get immediate notifications when a verification completes.

Vouchsafe will make POST requests to that URL with a request body like:

{
	"event": Created | UserComplete | Verified | Refused, // reason for the notification
	"id": "string",
	"status": "InProgress",
	"verificationMethod": "Document",
	"createdAt": "string",
	"email": "string"
}

See the full list of supported events.