> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verifyyou.com/llms.txt
> Use this file to discover all available pages before exploring further.
# External IDs
> Tie verifications to your own user identifiers.
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.
```javascript Node.js theme={null}
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();
```
```python Python theme={null}
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()
```
```typescript TypeScript theme={null}
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();
```
```csharp C# theme={null}
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();
```
```java Java theme={null}
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());
```
```php PHP theme={null}
$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);
```
```go Go theme={null}
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:
```javascript Node.js theme={null}
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!");
}
```
```python Python theme={null}
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!")
```
```typescript TypeScript theme={null}
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();
```
```csharp C# theme={null}
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();
```
```java Java theme={null}
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());
```
```php PHP theme={null}
$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!";
}
```
```go Go theme={null}
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()
```
```json Response theme={null}
{
"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.
```json First call theme={null}
{
"external_id": "user_8f3a29c1",
"verification_url": "https://verifyyou.com/i/A3KF9X"
}
```
```json Second call (same external_id) theme={null}
{
"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:
```json theme={null}
{
"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`:
```json theme={null}
{
"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.