External IDs - VerifyYou

Optionally tie a verification to your own user identifier by passing external_id. This lets you look up status later by your own ID instead of storing ours.

const response = await fetch("https://api.connect.verifyyou.com/v2/verification/create", {
  method: "POST",
  headers: {
    "API-KEY": process.env.VERIFYYOU_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    redirect: "https://yourapp.com/verified",
    external_id: "user_8f3a29c1",
  }),
});

const data = await response.json();

import requests

response = requests.post(
    "https://api.connect.verifyyou.com/v2/verification/create",
    headers={"API-KEY": VERIFYYOU_API_KEY},
    json={
        "redirect": "https://yourapp.com/verified",
        "external_id": "user_8f3a29c1",
    },
)

data = response.json()

const response = await fetch("https://api.connect.verifyyou.com/v2/verification/create", {
  method: "POST",
  headers: {
    "API-KEY": process.env.VERIFYYOU_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    redirect: "https://yourapp.com/verified",
    external_id: "user_8f3a29c1",
  }),
});

const data: { verification_url: string; external_id: string } = await response.json();

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("API-KEY", Environment.GetEnvironmentVariable("VERIFYYOU_API_KEY"));

var response = await client.PostAsync(
    "https://api.connect.verifyyou.com/v2/verification/create",
    new StringContent(
        """{"redirect": "https://yourapp.com/verified", "external_id": "user_8f3a29c1"}""",
        System.Text.Encoding.UTF8,
        "application/json"
    )
);

var body = await response.Content.ReadAsStringAsync();

var request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.connect.verifyyou.com/v2/verification/create"))
    .header("Content-Type", "application/json")
    .header("API-KEY", System.getenv("VERIFYYOU_API_KEY"))
    .POST(HttpRequest.BodyPublishers.ofString(
        "{\"redirect\": \"https://yourapp.com/verified\", \"external_id\": \"user_8f3a29c1\"}"
    ))
    .build();

var response = client.send(request, HttpResponse.BodyHandlers.ofString());

$response = file_get_contents("https://api.connect.verifyyou.com/v2/verification/create", false,
    stream_context_create(["http" => [
        "method" => "POST",
        "header" => "Content-Type: application/json\r\nAPI-KEY: " . $apiKey,
        "content" => json_encode([
            "redirect" => "https://yourapp.com/verified",
            "external_id" => "user_8f3a29c1",
        ]),
    ]])
);

$data = json_decode($response, true);

body, _ := json.Marshal(map[string]string{
    "redirect":    "https://yourapp.com/verified",
    "external_id": "user_8f3a29c1",
})

req, _ := http.NewRequest("POST",
    "https://api.connect.verifyyou.com/v2/verification/create",
    bytes.NewBuffer(body),
)
req.Header.Set("Content-Type", "application/json")
req.Header.Set("API-KEY", os.Getenv("VERIFYYOU_API_KEY"))

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

Once set, you can check status by your own ID instead of the token:

const response = await fetch("https://api.connect.verifyyou.com/v2/verification/status", {
  method: "POST",
  headers: {
    "API-KEY": process.env.VERIFYYOU_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ external_id: "user_8f3a29c1" }),
});

const data = await response.json();
if (data.verification_complete) {
  console.log("User is verified!");
}

response = requests.post(
    "https://api.connect.verifyyou.com/v2/verification/status",
    headers={"API-KEY": VERIFYYOU_API_KEY},
    json={"external_id": "user_8f3a29c1"},
)

data = response.json()
if data["verification_complete"]:
    print("User is verified!")

const response = await fetch("https://api.connect.verifyyou.com/v2/verification/status", {
  method: "POST",
  headers: {
    "API-KEY": process.env.VERIFYYOU_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ external_id: "user_8f3a29c1" }),
});

const data: { verification_complete: boolean; external_id: string } = await response.json();

var response = await client.PostAsync(
    "https://api.connect.verifyyou.com/v2/verification/status",
    new StringContent(
        """{"external_id": "user_8f3a29c1"}""",
        System.Text.Encoding.UTF8,
        "application/json"
    )
);

var body = await response.Content.ReadAsStringAsync();

var request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.connect.verifyyou.com/v2/verification/status"))
    .header("Content-Type", "application/json")
    .header("API-KEY", System.getenv("VERIFYYOU_API_KEY"))
    .POST(HttpRequest.BodyPublishers.ofString(
        "{\"external_id\": \"user_8f3a29c1\"}"
    ))
    .build();

var response = client.send(request, HttpResponse.BodyHandlers.ofString());

$response = file_get_contents("https://api.connect.verifyyou.com/v2/verification/status", false,
    stream_context_create(["http" => [
        "method" => "POST",
        "header" => "Content-Type: application/json\r\nAPI-KEY: " . $apiKey,
        "content" => json_encode(["external_id" => "user_8f3a29c1"]),
    ]])
);

$data = json_decode($response, true);
if ($data["verification_complete"]) {
    echo "User is verified!";
}

body, _ := json.Marshal(map[string]string{
    "external_id": "user_8f3a29c1",
})

req, _ := http.NewRequest("POST",
    "https://api.connect.verifyyou.com/v2/verification/status",
    bytes.NewBuffer(body),
)
req.Header.Set("Content-Type", "application/json")
req.Header.Set("API-KEY", os.Getenv("VERIFYYOU_API_KEY"))

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

Response

{
  "verification_complete": true,
  "external_id": "user_8f3a29c1"
}

If you pass both external_id and region, the person is still limited to one account per region, but can connect to new regions instantly without redoing the liveness check.

Reusing the same `external_id`

Calling verification/create more than once with the same external_id is not an error. Each call returns its own verification_url: independent, both valid. Nothing is overwritten on our side.

First call

{
  "external_id": "user_8f3a29c1",
  "verification_url": "https://verifyyou.com/i/A3KF9X"
}

Second call (same external_id)

{
  "external_id": "user_8f3a29c1",
  "verification_url": "https://verifyyou.com/i/Z9PQ2R"
}

This is intentional: external_id identifies your user, not a single verification attempt. You might legitimately want multiple URLs for the same user, e.g. one for email delivery, one for a fallback SMS, and we don’t want to block that.

How status resolves a reused `external_id`

verification/status answers at the user level, not the session level. It returns one boolean:

{
  "verification_complete": true,
  "external_id": "user_8f3a29c1"
}

If any session for that external_id has completed verification, verification_complete is true.
If all are still in-flight, verification_complete is false (200, safe to poll).

If no session has ever been created for that external_id, you get a 404 with failure_code: DOES_NOT_EXIST:

{
  "status": "failure",
  "failure_code": "DOES_NOT_EXIST",
  "failure_reason": "User not found"
}

Status does not enumerate the individual verification attempts behind an external_id; it answers at the user level. If you need to track individual attempts (e.g. retry analytics, expiring stale URLs), store the verification_url from each verification/create response yourself.

​Reusing the same external_id

​How status resolves a reused external_id

Reusing the same `external_id`

How status resolves a reused `external_id`