SmartLocator Address Verification API

1. Introduction

SmartLocator helps teams clean, standardise, and classify Indian shipping addresses. This guide documents the public API endpoints, authentication, request formats, and result handling for integrating address verification into your own software.

For the product’s address, order-intelligence, and delivery-risk concepts, see the SmartLocator feature report.

2. API Overview

https://smartlocator.in

3. Authentication

Every request must include your API key as a bearer token. Do not use a real key in examples, browser code, screenshots, or public repositories.

Authorization: Bearer <YOUR_API_KEY>

Use Content-Type: application/json for Single Verification and Bulk job submission. Result downloads return CSV content.

4. Single Address Verification Primary API

Verify one address per request and receive a JSON result you can use in your own software. Your customer records, order schema, database columns, and internal field names can stay as they are: map the address value to address and optionally pass the customer name as customerName. You do not need to send order ID, product, phone, payment status, or other fields unless your own application needs them separately.

5. Common Integration Use Cases

The Single API is designed to fit around the client’s existing data. The client’s integration reads an address from its own source, sends one request, then stores or displays the returned result.

6. Single API Request

Send JSON with the raw address and optional customerName. The implementation requires an address, accepts one address per request, and requires the raw address to contain at least 5 words.

curl -X POST "https://smartlocator.in/api/single-verify" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "DLF Phase 1 Gurgaon 122002",
    "customerName": "Ravi Kumar"
  }'

const response = await fetch("https://smartlocator.in/api/single-verify", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SMART_LOCATOR_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    address: "DLF Phase 1 Gurgaon 122002",
    customerName: "Ravi Kumar"
  })
});

import os, requests

response = requests.post(
    "https://smartlocator.in/api/single-verify",
    headers={
        "Authorization": f"Bearer {os.environ['SMART_LOCATOR_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={"address": "DLF Phase 1 Gurgaon 122002", "customerName": "Ravi Kumar"},
)

7. Single API Response

A successful response returns cleaned customer and address components, quality classification, and remaining credits when available. The values below are illustrative; use the fields and values returned by your actual request.

{
  "status": "Success",
  "customerCleanName": "Ravi Kumar",
  "addressLine1": "Tower A, DLF Phase 1, Gurgaon",
  "landmark": "Near DLF City Club",
  "district": "Gurgaon",
  "state": "Haryana",
  "pin": "122002",
  "addressQuality": "Good",
  "remainingCredits": 2488
}

8. Bulk Verification (Optional)

Bulk Verification submits a file for background processing. It does not return all verified rows in the first response. Your integration must submit the file, save the returned jobId, check the job status, and then download the result file or files.

Step 1 — Prepare the file

• Supported file extensions: .csv, .xlsx, and .xls.
• Maximum size by row count: up to 2,000 address rows per job.
• For CSV, send the CSV contents as a string in csvData and include totalRows.
• For Excel, send the original file bytes encoded as Base64 in csvData; totalRows is not required.
• Use a filename with the correct extension. Keep the original header row and columns in the uploaded file so the processor can interpret the data.

Step 2 — Submit a CSV job

Send a JSON request from your server. Replace the example data with your own CSV text. In this example, totalRows is 1 because there is one data row after the header.

curl -X POST "https://smartlocator.in/api/bulk-jobs" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "orders.csv",
    "totalRows": 1,
    "csvData": "ORDER ID,CUSTOMER NAME,CUSTOMER RAW ADDRESS\\n1001,Ravi Kumar,DLF Phase 1 Gurgaon 122002"
  }'

A successful submission returns a job identifier. Save this value; you will need it for status checks and downloads.

{
  "status": "Success",
  "jobId": "<JOB_ID>"
}

Step 3 — Check job status

Send the same bearer-token authorization header. Check the response for your job and wait until its status is Completed before attempting downloads. Do not assume that a submitted job has already finished.

curl -X GET "https://smartlocator.in/api/bulk-jobs" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Step 4 — Download Ready for Shipment results

Once the job is completed, request the Ready output using type=ready. The response is a CSV file, not a JSON object.

curl -L "https://smartlocator.in/api/bulk-jobs?action=download&jobId=<JOB_ID>&type=ready" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -o ready-for-shipment.csv

Step 5 — Download Manual Check Needed results

If you need the addresses that require review, make a separate request using type=manual. Do not use type=ready for this download.

curl -L "https://smartlocator.in/api/bulk-jobs?action=download&jobId=<JOB_ID>&type=manual" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -o manual-check-needed.csv

Tip: You can download both files for the same jobId. Store them separately or import each into the matching tab in your own application. A download may return a not-found response if the job is not completed, the job does not belong to the authenticated client, or the requested output is not available.

Excel file submission

For an Excel file, Base64-encode the original binary file bytes, not the filename or a text export, and place that Base64 string in csvData. Example request shape:

{
  "filename": "orders.xlsx",
  "csvData": "<BASE64_OF_ORIGINAL_XLSX_FILE_BYTES>"
}

Encode the file in your backend before making the request. Avoid putting large file contents directly into browser code or logs.

Bulk limits and common issues

• Only one active Bulk job can run per client at a time. Wait for the existing job to finish before submitting another.
• Your account needs an active plan and sufficient verification credits.
• For CSV uploads, include totalRows and ensure it matches the number of address/data rows you are submitting, not the header row.
• Use the exact job ID returned by submission and send the API key that owns that job.
• Do not repeatedly retry an unchanged request after an authentication, validation, plan, or credit error. Fix the reported issue first.
• Keep your API key on the server. Do not expose it in public JavaScript, mobile app bundles, or a public repository.

9. Single vs Bulk Comparison

10. Limits, Credits, and Errors

Bulk uploads support up to 2,000 usable address rows per job. Before a Bulk job starts, the backend checks that the client has an active plan and enough credits for the submitted addresses. Only one active Bulk job can run at a time. If another job is already running, the API may return HTTP 429 until it finishes.

Handle non-2xx responses and inspect the returned JSON status and message. Errors can indicate missing or invalid authentication, a revoked or expired key, an expired plan, missing or invalid file data, insufficient credits, an unsupported file type, an active-job limit, missing download parameters, or an output that is not available yet. Do not repeatedly retry the same request without correcting the reported issue.

11. Security Best Practices

• Keep API keys secret and rotate them if exposure is suspected.
• Never expose API keys in public browser JavaScript.
• Never commit API keys to Git.
• Store API keys in environment variables or secure server-side secret storage.
• Use HTTPS for every request.
• Log request IDs and job IDs, but do not log full API keys or sensitive customer data unnecessarily.
• Handle 401 and 403 responses by stopping retries and prompting an operator to refresh credentials or plan status.

Test Lab Help & Troubleshooting

Use this section to get started with the Test Lab and troubleshoot common errors. For the endpoint request formats and full code examples, use the sections above and the Test Lab's Docs & Integration Examples tab.

Common problems and next steps

12. Recommended Integration Flow

1. Generate an API key from the SmartLocator client portal.
2. Store the key server-side as SMART_LOCATOR_API_KEY; never expose it in browser code.
3. Extract the raw address from your own order, CRM, or database record and send it as address. Pass customerName only if available and useful.
4. Handle the JSON response and map returned fields to your own data model.
5. Handle errors, credit limits, and plan status; avoid blind retries for validation or authentication failures.
6. Use the Bulk API only if you need your own software to submit and track batch files automatically. For manual spreadsheet uploads, use the dashboard.

Ready for Shipment is a verification/classification result, not a delivery guarantee. Manual Check Needed is a review signal, not an automatic invalid-address result. For a fuller integration overview, see the integration guide.