API reference OpenAPI 3.1
POST /verify/sessions/{id}:submit-address

Address leg (opt-in): postcode + free-text address vs the NG postcode registry (X-Verify-Token)

Bearer API key or staff session application/json operation submitVerifyAddress

Parameters

NameInTypeRequiredDescription
id path string Yes —

Request

Content type: application/json · required

FieldTypeRequiredDescription
postcode string No NIPOST postcode AA-99-H77-BB-55, any written form; malformed input is a 422, never a registry call
address_text string No free-text address kept as the declared snapshot
device_geo object No optional integrator-supplied position {lat, lon}; with L5 geometry (or sandbox points) the building-to-device distance decides mismatch beyond 50km
Show 2 nested fields
FieldTypeRequiredDescription
lat number No —
lon number No —
curl -X POST "$MONICHEK_API/verify/sessions/{id}:submit-address" \
  -H "Authorization: Bearer $MONICHEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "postcode": "string",
  "address_text": "string",
  "device_geo": {
    "lat": 1,
    "lon": 1
  }
}'
const res = await fetch(`${MONICHEK_API}/verify/sessions/{id}:submit-address`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${MONICHEK_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "postcode": "string",
    "address_text": "string",
    "device_geo": {
      "lat": 1,
      "lon": 1
    }
  }),
});

const data = await res.json();
import os
import requests

res = requests.post(
    f"{os.environ['MONICHEK_API']}/verify/sessions/{id}:submit-address",
    headers={"Authorization": f"Bearer {os.environ['MONICHEK_API_KEY']}"},
    json={
      "postcode": "string",
      "address_text": "string",
      "device_geo": {
        "lat": 1,
        "lon": 1
      }
    },
)
print(res.json())
$ch = curl_init(getenv('MONICHEK_API') . '/verify/sessions/{id}:submit-address');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('MONICHEK_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'postcode' => 'string',
        'address_text' => 'string',
        'device_geo' => [
            'lat' => 1,
            'lon' => 1,
        ],
    ]),
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Replace {id} with the resource id.

Responses

200 OK completed session; address.verification_state is verified (registry match) or declared_only — the combined verdict is untouched, address is a recorded signal application/json
{
  "object": "verify_result",
  "status": "completed",
  "session_id": "vs_01M3R...",
  "combined_decision": "approved",
  "risk_rating": "low",
  "address_verification_state": "verified",
  "address_postcode": "EK-01-A03-FK-01"
}

Error responses

StatusMeaningBody
401 Unauthorized RFC 9457 problem
409 Conflict RFC 9457 problem
422 Unprocessable Entity neither postcode nor address_text — or address.postcode_invalid on malformed input

Errors use the RFC 9457 problem format with a stable code.