Alias Token Queries

Use alias tokens to verify account status and compliance signals without handling personal identity data. JSON is the preferred interface for application integrations; DNS TXT lookups are available for resolver-based workflows.

What this is for

Query non-personal account and compliance signals for a Yoursafe YOU account using an alias token.

Recommended path

Use JSON queries for application integrations. Use DNS TXT queries for resolver-based environments.

Core checks

Check accountstatus, screening timestamps, and serial values to detect meaningful updates.

Method 1: JSON Queries (recommended)

Request

                  
                    GET https://<aliastoken>.yoursafe.id/?json=1

Response

Returns a JSON object with account status and compliance-related metadata.

                  {
  "aliastoken": "xyz123.yoursafe.id",
  "accountstatus": "active",
  "country": "Netherlands",
  "countrycode": "NL",
  "eighteenplus": true,
  "idverifieddate": "2022-07-21T06:27:33Z",
  "peplistdate": "2023-05-24T10:41:38Z",
  "sanctiondate": "2023-05-24T10:41:38Z",
  "uksanctionlists": "Negative",
  "unsanctionlists": "Negative",
  "ussanctionlists": "Negative",
  "eusanctionlists": "Negative",
  "ibanserials": ["a8999c4cbf0a1a67a3d0d4cf9cb7ea2b9a7d66301a93941f9ac2079597de39e1"]
}

JSON query reliability

Integrate JSON queries server-side, validate field types, and handle transient endpoint/network failures with retries.

Response field reference

aliastoken: Token identifier, usually <token>.yoursafe.id.
aliasserial: Serial that changes when significant alias/account data changes.
accountstatus: Current account state, typically active or inactive.
country, countrycode: Country details using ISO-3166 for countrycode.
eighteenplus: Boolean indicating whether the user is over 18.
idverifieddate: Last ID verification timestamp in UTC ISO-8601 format.
peplistdate, sanctiondate: Latest compliance screening timestamps.
uk/uns/us/eusanctionlists: Sanction list indicators, commonly Negative.
ibanserials: Array of serials related to associated IBANs.

Implementation checklist

Use backend-to-backend HTTPS calls and avoid exposing raw responses directly to clients.
Validate field presence and type before making compliance decisions.
Handle temporary network or endpoint failures with retries and graceful degradation.
Track serial/timestamp changes to trigger re-checks in your onboarding or monitoring flows.

Method 2: DNS TXT Queries

Request

                  
                    dig TXT accountstatus.<aliastoken>.yoursafe.id

Looks up a single field value from DNS TXT records.

Response

Example TXT answer

                  
                    accountstatus.xyz123.yoursafe.id. 300 IN TXT "active"

DNS TXT reliability

DNS responses are cache-sensitive. Design for TTL propagation and normalize TXT parsing across environments.

TXT record structure

Name: <field>.<aliastoken>.yoursafe.id
TTL: Cache duration in seconds as returned by DNS.
TXT value: The field value, for example "active".

Common fields

aliasserial accountstatus country countrycode eighteenplus idverifieddate peplistdate sanctiondate uksanctionlists unsanctionlists ussanctionlists eusanctionlists ibanserials

DNS checklist

Design for resolver caching and TTL delays before updates become visible.
Normalize TXT parsing because quoting/formatting can vary by tooling.
Use DNS when it matches your infrastructure; prefer JSON for richer app integration.

Operational best practices

Poll at intervals aligned with your compliance posture (on login, payout, or scheduled checks).
Persist latest values and compare new results to detect status transitions quickly.
Alert or pause sensitive flows when accountstatus is inactive or screening data is stale.
Log query outcomes for auditability, while minimizing retention of unnecessary metadata.

Endpoint Reference

Look up OIDC endpoints for discovery, tokens, userinfo, and logout.