> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.withverifa.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.withverifa.com/_mcp/server.

# Get the organization's proof-of-address policy

GET https://api.withverifa.com/api/v1/settings/proof-of-address

Returns the organization's stored proof-of-address settings plus
everything needed to edit them: the regional presets, the canonical
document-type table, and the country list.

`effective` is the policy resolved from built-in defaults, then the
named preset, then the stored settings — what a check would use if the
workflow node says "use organization settings". A workflow node that
overrides fields layers on top of this at run time.

Requires the `proof_of_address_check` feature on your plan (sandbox
unlocks it). Dashboard cookie only — not callable with an API key.


Reference: https://docs.withverifa.com/api-reference/organization-settings/get-proof-of-address-settings

## Request

### Headers

- `Verifa-Version` (date, optional) — API version date string (e.g. `2026-02-01`). If omitted, the version pinned to your API key is used.

## Response

### 200

The stored policy, the resolved policy, and the vocabulary needed to edit it.

- `presets` (map from string to map from string to any, required) — Regional starting points keyed by preset name (`custom`, `us`, `uk`, `eu`, `in`, `mx`, `au`, `ca`, `za`). Each is a partial policy — anything a preset omits keeps the default.
- `doc_types` (list of ApiV1SettingsProofOfAddressGetResponsesContentApplicationJsonSchemaDocTypesItems, required) — The canonical proof-of-address document types.
- `countries` (map from string to any, required) — Grouped ISO-2 country list for the country-override editor.
- `settings` (map from string to any, required) — The organization's stored policy overrides. `{}` when nothing is set.
- `effective` (PoaPolicySnapshot, required) — The effective proof-of-address policy this check ran under, resolved from four layers — built-in defaults, the regional preset, your organization's settings, then the workflow node's config, each overriding the last. Snapshotted into the result so a decision stays explainable after the policy changes.

## Errors

### 401 Unauthorized Error

Missing or invalid API key.

- `error` (string, required) — Short error code.
- `status_code` (integer, required) — HTTP status code.
- `detail` (string, optional) — Human-readable error description.

### 403 Forbidden Error

Proof-of-address checks are not available on this plan.

- `error` (string, required) — Short error code.
- `status_code` (integer, required) — HTTP status code.
- `detail` (string, optional) — Human-readable error description.

### 404 Not Found Error

Resource not found.

- `error` (string, required) — Short error code.
- `status_code` (integer, required) — HTTP status code.
- `detail` (string, optional) — Human-readable error description.

## Types

### ApiV1SettingsProofOfAddressGetResponsesContentApplicationJsonSchemaDocTypesItems

- `key` (enum, required) — Canonical proof-of-address document subtype. This is the vocabulary the capture flow, the workflow node, and the check result all share. Legacy values are still accepted on input and normalised on the way in: `rental_agreement` → `lease_agreement`, `vehicle_registration` → `government_letter`. `lease_agreement`, `institution_letter`, and `other` have no official issuer, so a passing result on one of them still routes to human review. `id_with_address` is not an independent source — it shares its issuer with the ID document — and is only accepted when the policy opts in.
  - Allowed values: `utility_bill`, `mobile_phone_bill`, `bank_statement`, `credit_card_statement`, `council_tax`, `tax_document`, `government_letter`, `benefits_letter`, `mortgage_statement`, `lease_agreement`, `insurance_statement`, `payslip`, `id_with_address`, `institution_letter`, `other`
- `label` (string, required)
- `category` (enum, required)
  - Allowed values: `utility`, `financial`, `government`, `housing`, `employment`, `identity`, `other`
- `default_max_age_days` (integer, required) — Recency window before any organization or country override.
- `review_only` (boolean, optional) — No official issuer — a pass still routes to human review.
- `counts_as_independent` (boolean, optional) — False when the document shares its source with the ID document.

### PoaPolicySnapshot

The effective proof-of-address policy this check ran under, resolved from four layers — built-in defaults, the regional preset, your organization's settings, then the workflow node's config, each overriding the last. Snapshotted into the result so a decision stays explainable after the policy changes.

- `preset` (enum, optional)
  - Allowed values: `custom`, `us`, `uk`, `eu`, `in`, `mx`, `au`, `ca`, `za`
- `accepted_types` (list of enum, optional) — Empty means every non-review-only type is accepted.
  - Allowed values: `utility_bill`, `mobile_phone_bill`, `bank_statement`, `credit_card_statement`, `council_tax`, `tax_document`, `government_letter`, `benefits_letter`, `mortgage_statement`, `lease_agreement`, `insurance_statement`, `payslip`, `id_with_address`, `institution_letter`, `other`
- `max_age_days_by_type` (map from string to integer, optional) — Per-type recency windows layered over each type's default.
- `country_overrides` (map from string to map from string to any, optional) — ISO-2 country code → `{accepted_types, max_age_days_by_type}`, applied when the document's issuing country matches.
- `allow_po_box` (boolean, optional)
- `allow_business_address` (boolean, optional)
- `allow_screenshots` (boolean, optional)
- `allow_mobile_phone_bill` (boolean, optional)
- `id_with_address_satisfies` (boolean, optional)
- `require_declared_address` (boolean, optional) — Guided flow. When false the flow is unguided — the address is extracted but never scored against a reference, and the check reports `address_not_compared`.
- `address_source` (enum, optional)
  - Allowed values: `user_declared`, `id_document`
- `name_match_pass` (double, optional)
- `name_match_review` (double, optional)
- `address_match_pass` (double, optional)
- `address_match_review` (double, optional)
- `date_match_tolerance_days` (integer, optional)
- `classifier_disagreement` (enum, optional)
  - Allowed values: `review`, `ignore`, `fail`
- `country_mismatch_action` (enum, optional)
  - Allowed values: `review`, `ignore`, `fail`
- `max_age_days` (integer, optional, nullable) — Legacy flat window, expanded across every type at resolution time.

## Examples

**Response**

```json
{
  "presets": {},
  "doc_types": [
    {
      "key": "utility_bill",
      "label": "Council tax / property tax / rates",
      "category": "utility",
      "default_max_age_days": 1,
      "review_only": true,
      "counts_as_independent": true
    }
  ],
  "countries": {},
  "settings": {},
  "effective": {
    "preset": "custom",
    "accepted_types": [
      "utility_bill"
    ],
    "max_age_days_by_type": {},
    "country_overrides": {},
    "allow_po_box": true,
    "allow_business_address": true,
    "allow_screenshots": true,
    "allow_mobile_phone_bill": true,
    "id_with_address_satisfies": true,
    "require_declared_address": true,
    "address_source": "user_declared",
    "name_match_pass": 1.1,
    "name_match_review": 1.1,
    "address_match_pass": 1.1,
    "address_match_review": 1.1,
    "date_match_tolerance_days": 1,
    "classifier_disagreement": "review",
    "country_mismatch_action": "review",
    "max_age_days": 1
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.withverifa.com/api/v1/settings/proof-of-address"

response = requests.get(url)

print(response.json())
```

```javascript
const url = 'https://api.withverifa.com/api/v1/settings/proof-of-address';
const options = {method: 'GET'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.withverifa.com/api/v1/settings/proof-of-address"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.withverifa.com/api/v1/settings/proof-of-address")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.withverifa.com/api/v1/settings/proof-of-address")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.withverifa.com/api/v1/settings/proof-of-address');

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.withverifa.com/api/v1/settings/proof-of-address");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.withverifa.com/api/v1/settings/proof-of-address")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```