How do you setup identity or age verification so that only certain locations need to get verified?

darrin

13 Jan 2026 — 5 min read

Answer: Use Location-Based Identity Verification. This is enabled via the locationRestrictions.requiresVerification attribute in your application configuration to define which countries and regions require verification.

Summary

Token of Trust now supports location-based verification requirements through the locationRestrictions configuration. This feature allows you to specify which geographic locations (countries and regions) require identity or age verification, while exempting others. The system intelligently uses the transactional shipping address when available, falling back to the person's primary location if not.

Configuration

Basic Structure

The requiresVerification attribute is configured within workflow.verifyPerson.locationRestrictions in your application options:

{
  "workflow": {
    "verifyPerson": {
      "locationRestrictions": {
        "defaults": {
          "shipTo": true,
          "requiresVerification": false
        },
        "US": {
          "CA": {
            "requiresVerification": true
          }
        }
      }
    }
  }
}

Configuration Hierarchy

The locationRestrictions configuration follows a hierarchical structure with cascading defaults:

Global defaults - Applied to all locations unless overridden
Country-level rules - Override defaults for specific countries
Region-level rules - Override country and global defaults for specific regions

{
  "locationRestrictions": {
    "defaults": {
      "requiresVerification": false  // Global default: no verification required
    },
    "US": {
      "defaults": {
        "requiresVerification": false  // US default (optional, inherits from global)
      },
      "CA": {
        "requiresVerification": true  // California requires verification
      },
      "NY": {
        "requiresVerification": true  // New York requires verification
      }
    },
    "GB": {
      "requiresVerification": true  // All of UK requires verification
    }
  }
}

How It Works

Location Priority

The verification system determines the customer's location using the following priority order:

appData.shippingAddress - Primary transactional shipping address
appData.shippingLocation - Alternative transactional location
body.shippingAddress - Request body shipping address
body.shipping_address - Common e-commerce payload format
person.shippingAddress - Person's shipping address
person.shippingLocation - Person's shipping location
person.location - Fallback to person's primary location

Key Insight: The system prefers transactional shipping information (where the order is being sent) over the person's profile location. This ensures that verification requirements are based on where the product is being delivered, not where the customer lives.

Region Code Handling

The system recognizes multiple region code formats:

regionCode
region
provinceCode
province
stateCode
state

This flexibility ensures compatibility with various data formats from different e-commerce platforms.

Rule Resolution

When evaluating whether verification is required:

Country matching - System identifies the country from countryCode or countryName
Region matching - If a region code exists, system looks for region-specific rules
Default cascading - Rules cascade from: Region → Country defaults → Global defaults
Verification decision - If requiresVerification: false is found, verification is skipped

Common Use Cases

Use Case 1: Single State Requirement (California Only)

Scenario: Only customers in California need age verification for cannabis products.

Configuration:

{
  "workflow": {
    "verifyPerson": {
      "locationRestrictions": {
        "defaults": {
          "requiresVerification": false
        },
        "US": {
          "CA": {
            "requiresVerification": true
          }
        }
      }
    }
  }
}

Result:

California customers (US/CA): Verification required
All other locations: No verification required

Use Case 2: Multiple States

Scenario: Age verification required in California, New York, and Massachusetts.

Configuration:

{
  "workflow": {
    "verifyPerson": {
      "locationRestrictions": {
        "defaults": {
          "requiresVerification": false
        },
        "US": {
          "CA": {
            "requiresVerification": true
          },
          "NY": {
            "requiresVerification": true
          },
          "MA": {
            "requiresVerification": true
          }
        }
      }
    }
  }
}

Use Case 3: Country-Wide Requirement

Scenario: All UK customers need verification, but other countries don't.

Configuration:

{
  "workflow": {
    "verifyPerson": {
      "locationRestrictions": {
        "defaults": {
          "requiresVerification": false
        },
        "GB": {
          "defaults": {
            "requiresVerification": true
          }
        }
      }
    }
  }
}

Result:

All UK regions: Verification required
All other countries: No verification required

Use Case 4: All Require Verification Except Specific Regions

Scenario: Verification required everywhere in the US except for a few exempted states.

Configuration:

{
  "workflow": {
    "verifyPerson": {
      "locationRestrictions": {
        "defaults": {
          "requiresVerification": true
        },
        "US": {
          "defaults": {
            "requiresVerification": true
          },
          "AK": {
            "requiresVerification": false
          },
          "HI": {
            "requiresVerification": false
          }
        }
      }
    }
  }
}

Integration with Existing Features

Relationship to `includedCountries`

The locationRestrictions.requiresVerification feature works in conjunction with the existing includedCountries configuration:

First check: includedCountries determines if verification runs at all for this country
Second check: locationRestrictions.requiresVerification determines if verification is required for the specific location

Example:

{
  "workflow": {
    "verifyPerson": {
      "includedCountries": ["US", "CA", "MX"],
      "locationRestrictions": {
        "defaults": {
          "requiresVerification": false
        },
        "US": {
          "CA": {
            "requiresVerification": true
          }
        }
      }
    }
  }
}

Result:

Verifications can run in US, Canada, and Mexico (via includedCountries)
But only California (US/CA) requires verification

Co-location with Other Location Rules

The requiresVerification attribute is intentionally placed within locationRestrictions alongside other location-based rules like shipTo. This keeps all location-based business logic centralized:

{
  "locationRestrictions": {
    "US": {
      "CA": {
        "shipTo": true,
        "requiresVerification": true
      },
      "NY": {
        "shipTo": false,
        "requiresVerification": false
      }
    }
  }
}

Response Details

When Verification is Not Required

When a location does not require verification, the system returns detailed information in the response:

{
  verificationNotRequiredForVendor: {
    value: 'fullMatch',
    details: {
      locationDoesNotRequireVerification: true,
      countryCode: 'US',
      regionCode: 'TX'
    }
  }
}

This provides clear audit trail information about why verification was skipped.

Implementation Details

Module Location

Configuration: services/apiKeyService/apiKeyOptions.md
Implementation: website/modules/steps/verificationRequired/verificationRequired.node.js
Rule Engine: modules/locationRestrictions/locationRestrictions.node.js
Tests: website/modules/steps/verificationRequired/verificationRequired.test.js

Key Functions

`getVerificationLocation(req)`

Determines which location to use for verification checks, prioritizing transactional shipping addresses.

`getRegionCode(location)`

Extracts region/state/province code from various possible location object formats.

`LocationRestrictions.getLocationRestrictionRule(options, callback)`

Retrieves the applicable rule for a given location, handling country and region-level defaults.

Testing

The feature includes comprehensive test coverage:

Requires verification for matching region - Verifies that CA customers are required to verify
Does not require verification for other regions - Verifies that TX customers are not required
Prefers transactional shipping address - Verifies that shipping address takes precedence over person location

Test Example

const person = {location: {countryCode: 'US', regionCode: 'TX'}};
const apiClient = testUtils.buildApiClient({
  options: {
    workflow: {
      verifyPerson: {
        locationRestrictions: {
          "defaults": {
            "requiresVerification": false
          },
          "US": {
            "CA": {
              "requiresVerification": true
            }
          }
        }
      }
    }
  }
});

// Result: Texas customer does NOT require verification

Configuration Guidelines

Best Practices

Set clear defaults - Always define a global default to handle unexpected locations
Use region codes carefully - Ensure region codes match your data format (state codes, province codes, etc.)
Test with shipping addresses - Remember that shipping addresses take precedence
Document your rules - Keep track of which locations require verification and why
Consider cascading - Use country defaults when most regions in a country share the same rule

Common Pitfalls

Forgetting global defaults - Without a default, unexpected locations may fail
Use of region names rather than codes - "CA" - YES! "California" - NO!
Not testing shipping vs person location - The priority order matters for accurate verification

Migration from `includedCountries` Only

If you're currently using only includedCountries for verification control:

Before:

{
  "workflow": {
    "verifyPerson": {
      "includedCountries": ["US"]  // All US customers require verification
    }
  }
}

After (with region-specific control):

{
  "workflow": {
    "verifyPerson": {
      "includedCountries": ["US"],  // Verification available in US
      "locationRestrictions": {
        "defaults": {
          "requiresVerification": false  // But not required by default
        },
        "US": {
          "CA": {
            "requiresVerification": true  // Except in California
          }
        }
      }
    }
  }
}

Frequently Asked Questions

Q: What happens if I don't set requiresVerification at all?
A: The system maintains backward compatibility. If locationRestrictions is not configured, the existing includedCountries logic applies (verification required for all included countries).

Q: Can I require verification at the country level but exempt specific regions?
A: Yes! Set requiresVerification: true in the country's defaults, then override with requiresVerification: false for specific regions.

Q: What if the customer's location and shipping address are in different states?
A: The shipping address takes precedence. Verification requirements are based on where the product is being delivered.

Q: How do I verify the configuration is working correctly?
A: Check the response details when verification is not required. It includes locationDoesNotRequireVerification, countryCode, and regionCode for debugging.

Q: Does this work with international addresses?
A: Yes! You can configure rules for any country code (US, GB, CA, etc.) and their respective regions.

Summary

The locationRestrictions.requiresVerification feature provides fine-grained control over identity and age verification requirements based on geographic location. By using hierarchical configuration with intelligent defaults and prioritizing transactional shipping addresses, it enables compliance with location-specific regulations while minimizing friction for customers in other areas.

Key Takeaways:

Configure requiresVerification within workflow.verifyPerson.locationRestrictions
System uses shipping address when available, falls back to person location
Rules cascade from global defaults → country defaults → region-specific rules
Works alongside existing includedCountries for comprehensive verification control
Provides detailed response information for audit trails

API Key Options: services/apiKeyService/apiKeyOptions.md - Full configuration reference
Location Restrictions Module: modules/locationRestrictions/locationRestrictions.node.js - Rule engine implementation
Verification Required Step: website/modules/steps/verificationRequired/verificationRequired.node.js - Integration point

Document Version: 1.0
Last Updated: January 2026
Feature Added: Commit 09f116a4e (January 5, 2026)

How do you setup identity or age verification so that only certain locations need to get verified?

darrin

Summary

Configuration

Basic Structure

Configuration Hierarchy

How It Works

Location Priority

Region Code Handling

Rule Resolution

Common Use Cases

Use Case 1: Single State Requirement (California Only)

Use Case 2: Multiple States

Use Case 3: Country-Wide Requirement

Use Case 4: All Require Verification Except Specific Regions

Integration with Existing Features

Relationship to `includedCountries`

Co-location with Other Location Rules

Response Details

When Verification is Not Required

Implementation Details

Module Location

Key Functions

`getVerificationLocation(req)`

`getRegionCode(location)`

`LocationRestrictions.getLocationRestrictionRule(options, callback)`

Testing

Test Example

Configuration Guidelines

Best Practices

Common Pitfalls

Migration from `includedCountries` Only

Frequently Asked Questions

Summary

Read more

Approach: Improve Bot Discoverability with Search and Team Scoping

Browse & Search Licenses

License Details (View‑Only)

cd_release Link Docs Test

Summary

Configuration

Basic Structure

Configuration Hierarchy

How It Works

Location Priority

Region Code Handling

Rule Resolution

Common Use Cases

Use Case 1: Single State Requirement (California Only)

Use Case 2: Multiple States

Use Case 3: Country-Wide Requirement

Use Case 4: All Require Verification Except Specific Regions

Integration with Existing Features

Relationship to includedCountries

Co-location with Other Location Rules

Response Details

When Verification is Not Required

Implementation Details

Module Location

Key Functions

getVerificationLocation(req)

getRegionCode(location)

LocationRestrictions.getLocationRestrictionRule(options, callback)

Testing

Test Example

Configuration Guidelines

Best Practices

Common Pitfalls

Migration from includedCountries Only

Frequently Asked Questions

Summary

Related Documentation

Read more

Approach: Improve Bot Discoverability with Search and Team Scoping

Browse & Search Licenses

License Details (View‑Only)

cd_release Link Docs Test

Relationship to `includedCountries`

`getVerificationLocation(req)`

`getRegionCode(location)`

`LocationRestrictions.getLocationRestrictionRule(options, callback)`

Migration from `includedCountries` Only