Resolve Endpoint

This endpoint is only relevant when using server mode. In client mode, the SDK calls it for you and returns the full address object directly to your onSuccess callback. No backend call is needed.

In server mode, your onSuccess callback receives a short-lived requestId instead. Your frontend forwards it to your own backend, which exchanges it for the full address object here. This is the only Geophrase API call your backend makes.

Endpoint

POST https://api.geophrase.com/business/resolve/

Headers

Request Body

{
    "request_id": "abf380d5-b63a-4a8e-b677-d98cc62c12d4",
    "order_id": "ORD-8786",
    "note_for_agent": "Box 2. Call before arriving."
}

Example Request

curl --location 'https://api.geophrase.com/business/resolve/' \
--header 'X-API-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "request_id": "abf380d5-b63a-4a8e-b677-d98cc62c12d4",
    "order_id": "ORD-8786"
}'

Success Response

Status: 200 OK

{
    "short_code": "e6v9th",
    "short_link": "https://gphr.in/e6v9th",
    "qr_code": "https://storage.googleapis.com/geophrase/qr-codes/e6v9th.png",
    "captured_at": 1778485231452,
    "order_id": "ORD-8786",
    "address": {
        "city": "Bengaluru",
        "state": "Karnataka",
        "digi_pin": "275-8F6-9CC6",
        "landmark": "Map: gphr.in/e6v9th",
        "latitude": 12.935230,
        "longitude": 77.614500,
        "postal_code": 560103,
        "address_type": "OFFICE",
        "address_line_one": "Floor 4, Prestige Tech Park",
        "address_line_two": "Outer Ring Road",
        "contact_full_name": "Rohan Mehta",
        "verified_mobile_num": "9999999999"
    }
}

All fields are always present. order_id is an empty string when no order_id was supplied. landmark and address_line_two may be empty strings. No field is ever null.

See The Address Object for a full description of each field.

Idempotency and billing

A request_id is not single-use. You can call this endpoint with the same request_id any number of times and the response will be identical.

• Billing: The ₹2 resolve fee is charged only on the first successful resolution of a given request_id. Subsequent calls with the same request_id are free.
• Updating order_id: If you call the endpoint a second time with a different non-empty order_id, the stored order_id is updated to the new value (and reflected in the dashboard and in the response). Omitting order_id on a subsequent call leaves the stored value unchanged.
• Updating note_for_agent: Works like order_id. A later call with a non-empty note_for_agent replaces the stored note, and omitting it leaves the note unchanged. The note is never included in the response.
• Retries are safe: If your backend's first call fails (timeout, network error, 5xx), retry with the same request_id. You will not be double-charged.

Deferring the call

You are not required to call this endpoint the moment your frontend receives the requestId. Many merchants prefer to defer the call until the order is actually placed, because the resolve call is billed but selecting an address doesn't yet mean the customer will check out:

1. Customer picks an address in the widget. Your frontend receives { requestId } and stores it against the in-progress cart.
2. Customer proceeds to payment. If they abandon the cart, you never call resolve, so there is no charge.
3. Payment succeeds (or COD is confirmed). You now have a real internal order ID. Call the resolve endpoint with both request_id and your order_id.

If you need the resolved address earlier (for example, to display the formatted address back to the customer before payment), call resolve when you receive the requestId and pass your in-progress reference as order_id. Once the order is confirmed and you have the final order ID, call resolve again with the same request_id and the final order_id. The stored order_id is updated and the second call is free.

Error Responses

400 Bad Request

Returned when the request body is malformed or the Request ID cannot be processed.

402 Payment Required

Your wallet balance is insufficient to cover the resolution fee. The fee is ₹2 per first-time resolve; subsequent resolves of the same request_id are free. Top up your balance in the Geophrase Dashboard to continue.

403 Forbidden

Returned when the request cannot be authenticated or authorized.

See API Keys & Security for guidance on configuring restrictions.

Next step

The Address Object