Address Verification

Create passive address verification jobs and ingest location events from your mobile SDK.

Address verification job creation is a billed mutation. To make retries safe, POST /address-verification/jobs requires an Idempotency-Key header. Use one unique key for each logical job creation request and reuse that same key only when retrying the same request after a timeout or network failure.

Create a job

curl -X POST https://api.lira.com/api/v1/address-verification/jobs \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: YOUR_IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_ref": "CUSTOMER-001",
    "country_code": "ZM",
    "claimed_lat": -15.416,
    "claimed_lng": 28.283,
    "claimed_label": "Home",
    "observation_days": 14,
    "radius_meters": 100
  }'

Request body fields

Field	Type	Required	Description
`customer_ref`	string	Yes	Your unique reference for this customer.
`country_code`	string	Yes	ISO 3166-1 alpha-2 country code.
`claimed_lat`	number	No	Claimed home latitude. Defaults to `0` if not yet known.
`claimed_lng`	number	No	Claimed home longitude. Defaults to `0` if not yet known.
`claimed_label`	string	No	Human-readable label for the claimed location.
`observation_days`	number	No	Number of nights to observe. Defaults to `14`.
`tracking_window_start`	string	No	Nightly observation start time in `HH:MM`. Defaults to `20:00`.
`tracking_window_end`	string	No	Nightly observation end time in `HH:MM`. Defaults to `06:00`.
`radius_meters`	number	No	GPS match radius in meters. Defaults to `100`.

Response

{
  "job_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "pending",
  "created_at": "2026-04-01T10:00:00.000Z"
}

SDK retry keys

If you use a Lira SDK, pass an idempotencyKey option when creating an address verification job and persist it with your local job submission state:

await lira.addressVerification.createJob(
  {
    customer_ref: 'CUSTOMER-001',
    country_code: 'ZM',
    claimed_lat: -15.416,
    claimed_lng: 28.283,
  },
  { idempotencyKey: 'address-job-CUSTOMER-001-20260504' }
);

If no key is provided, SDKs should generate one per createJob call and reuse it for automatic retries inside that call. Durable retries across app restarts require you to provide and persist your own key.

Location event ingestion

Location event ingestion remains a high-volume telemetry endpoint and does not require Idempotency-Key in this phase.

curl -X POST https://api.lira.com/api/v1/address-verification/events \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "job_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "timestamp": "2026-04-01T22:30:00.000Z",
        "lat": -15.416,
        "lng": 28.283,
        "accuracy_meters": 12.5,
        "source": "gps",
        "source_type": "foreground",
        "power_event": false
      }
    ]
  }'

Idempotency errors

HTTP status	`error.code`	Meaning	Action
`422`	`IDEMPOTENCY_KEY_REQUIRED`	Missing `Idempotency-Key` header on job creation.	Generate a key and retry the same request.
`422`	`IDEMPOTENCY_KEY_INVALID`	Key is empty, too long, or contains unsupported characters.	Use 1-255 printable ASCII characters.
`409`	`IDEMPOTENCY_IN_PROGRESS`	The same key is already processing.	Wait briefly, then retry with the same key.
`409`	`IDEMPOTENCY_KEY_CONFLICT`	The same key was used with a different request body.	Generate a new key for the new request.

For the full error code reference, see Errors.

Managing Verifications

Overview