POST /address/match/batch — Match Addresses

Compare one source address against multiple target addresses. Returns similarity scores and same-person confidence for each match.

Submit a single source address alongside one or more target addresses. Atlas normalizes each address and returns a similarity_score and a same_person_score for every target. You can use these scores to determine whether two addresses on different documents belong to the same individual.

A 200 response does not guarantee all targets were successfully matched. Always check error_code on each result in match_data — per-target failures are reported inline rather than as top-level errors.

Endpoint

POST /v1/address/match/batch

Authentication

This endpoint uses static client credentials passed as request headers — it does not use a JWT token. Your client_id and client_secret are issued directly by Atlas and remain fixed.

Request headers

client_id · string · required

Your Atlas client identifier.

client_secret · string · required

Your Atlas client secret.

Request body

application_id · string · required

A unique identifier for the application or loan case this request belongs to (e.g., "lentra_app_001").

source_address · string · required

The primary address to match against all targets (e.g., "Flat 12, Green View Apartments, MG Road, Bangalore").

target_addresses · array · required

One or more addresses to compare against source_address. Must contain at least one item.

Show target_addresses item properties

address · string · required

The target address string to compare.

index · integer · required

A client-assigned integer index. Atlas echoes this back on each result so you can deterministically map responses to your input addresses.

Response

match_data · array

One result object per target address, in the same order as your input.

Show match_data item properties

source_address · string

Echo of the source_address you provided.

target_address · string

Echo of this target’s address value.

similarity_score · float | null

Address similarity as a percentage between 0 and 100. A higher score indicates a closer textual and semantic match. Returns null if matching failed for this target.

same_person_score · integer | null

Likelihood (on a scale of 0–10) that the source and target addresses belong to the same person. Returns null if matching failed for this target.

index · integer

The index value you provided for this target.

error_code · string | null

Per-target error code if this specific address could not be matched (e.g., "422"). null on success.

error_message · string | null

Human-readable description of the per-target error. null on success.

Error responses

Status	Meaning
400	Bad Request — source_address or target_addresses is missing or invalid.
401	Authentication Error — client_id or client_secret is invalid.
422	Unprocessable Entity — the source address or one or more targets could not be normalized.
503	Service Unavailable — the address matching engine is temporarily unavailable.

Example

cURL

curl --request POST \
  --url https://api.helloatlas.in/v1/address/match/batch \
  --header 'Content-Type: application/json' \
  --header 'client_id: <YOUR_CLIENT_ID>' \
  --header 'client_secret: <YOUR_CLIENT_SECRET>' \
  --data '{
    "application_id": "lentra_app_001",
    "source_address": "Flat 12, Green View Apartments, MG Road, Bangalore",
    "target_addresses": [
      {
        "address": "12 Greenview Apt, Mahatma Gandhi Rd, Bengaluru",
        "index": 0
      },
      {
        "address": "45 Lake View, Whitefield, Bangalore",
        "index": 1
      }
    ]
  }'

200 Response (full or partial success)

{
  "match_data": [
    {
      "source_address": "Flat 12, Green View Apartments, MG Road, Bangalore",
      "target_address": "12 Greenview Apt, Mahatma Gandhi Rd, Bengaluru",
      "similarity_score": 89.92,
      "same_person_score": 9,
      "index": 0,
      "error_code": null,
      "error_message": null
    },
    {
      "source_address": "Flat 12, Green View Apartments, MG Road, Bangalore",
      "target_address": "45 Lake View, Whitefield, Bangalore",
      "similarity_score": null,
      "same_person_score": null,
      "index": 1,
      "error_code": "422",
      "error_message": "Unprocessable Entity: Address normalization failed for this target"
    }
  ]
}

In the example above, the first target matched with a similarity_score of 89.92 and same_person_score of 9, while the second target failed normalization. The overall HTTP status is still 200 — always inspect each item’s error_code before using the scores.