curl --request GET \
--url https://api.baselayer.com/identities/principals \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.baselayer.com/identities/principals"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api.baselayer.com/identities/principals', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.baselayer.com/identities/principals",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.baselayer.com/identities/principals"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.baselayer.com/identities/principals")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.baselayer.com/identities/principals")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
response = http.request(request)
puts response.read_body[
{
"principal_ref": "<string>",
"display_name": "<string>",
"verification_state": "CURRENT",
"linked_business_count": 123,
"credentials_minted_30d": 123,
"verified_at": "2023-11-07T05:31:56Z",
"expires_at": "2023-11-07T05:31:56Z",
"verification_level": 123,
"active_keys": [
"<string>"
]
}
]{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}List the people your organization has verified
Lists every person your organization holds a prn_ reference for, newest verification first: their current verification state, what it can attest to, how many businesses they operate under your coverage, and how much credential activity they have seen. Filter by verification state, operator-link status and verification date; search by reference, name, email or phone. Scoped to your own population — references issued by other organizations are not listed and are not searchable.
curl --request GET \
--url https://api.baselayer.com/identities/principals \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.baselayer.com/identities/principals"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api.baselayer.com/identities/principals', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.baselayer.com/identities/principals",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.baselayer.com/identities/principals"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.baselayer.com/identities/principals")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.baselayer.com/identities/principals")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
response = http.request(request)
puts response.read_body[
{
"principal_ref": "<string>",
"display_name": "<string>",
"verification_state": "CURRENT",
"linked_business_count": 123,
"credentials_minted_30d": 123,
"verified_at": "2023-11-07T05:31:56Z",
"expires_at": "2023-11-07T05:31:56Z",
"verification_level": 123,
"active_keys": [
"<string>"
]
}
]{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Authorizations
Query Parameters
Maximum number of records to return in a single page. Must be between 1 and 1000.
1 <= x <= 1000Number of records to skip from the beginning. Use 0 for the first page. Cannot be used with cursor.
x >= 0Opaque pagination cursor token that identifies the position in the result set. Use the cursor from the previous response to get the next page. Cannot be used with offset.
Only identities in this derived state. SUPERSEDED never matches: the list carries one row per person — their current verification — and superseded snapshots are lineage, not population. Verification state of an identity, as seen by the referencing organization.
CURRENT: an unexpired verification exists and credentials can be minted. EXPIRED: the verification's validity window has lapsed — re-verify before minting. SUPERSEDED: no active verification record remains; a new submission is required.
CURRENT, EXPIRED, SUPERSEDED Only people holding at least one operator link in this status that your organization covered. Status of the link between a person (principal) and a business they operate.
VERIFIED is earned by the full evidence recipe (TIN provided + IRS-matched + KYB-verified) or granted by manual review; UNDER_REVIEW is every automatic shortfall; REJECTED is a manual refusal. A rejected link is immutable — a later submission evaluates the pair fresh.
VERIFIED, UNDER_REVIEW, REJECTED Only identities whose verification expires strictly before this instant — pass now + 30 days for the "expiring soon" needs-attention window. Already-expired identities match too; combine with verification_state to separate them. Must carry a UTC offset.
Only identities your active application saw a typed credential mint refusal for at or after this instant. Must carry a UTC offset.
A prn_ reference, or free text matched against name, email and phone. Every whitespace-separated term must match.
200Filter records created on or after this date (format: YYYY-MM-DD).
Filter records created on or before this date (format: YYYY-MM-DD).
IANA timezone identifier used to interpret start_date and end_date (defaults to UTC).
"UTC"
"America/Los_Angeles"
"Europe/London"
Response
Paginated identities, newest verification first, scoped to the calling organization.
This organization's pairwise reference to the person.
The verified name, as the latest snapshot recorded it. Mask it in shared surfaces; the API returns what the organization itself submitted.
CURRENT, or EXPIRED (re-verify before minting). Derived from the snapshot's validity window, never stored.
CURRENT, EXPIRED, SUPERSEDED Businesses this organization covers a live operator link to for the person; rejected links are not counted.
Credentials this organization minted for the person in the last 30 days, counting business credentials it acted for.
When the latest verification was recorded.
When the latest verification expires.
Verification level derived from active_keys; null when the attested attributes are insufficient for any defined level.
Dotted keys of the attributes the latest verification can attest to — the vocabulary credential disclosure uses.