Geo Data Handling

Quick reference — where geo comes from

1. RTB Inbound Request

When a publisher pings your RTB endpoint, they can supply location in the request body or query string.

Common parameters:

These keys are not prefixed with your postback key name — they apply directly to the call.

Example — explicit zip on RTB Inbound Request:

curl -X POST "https://rtb.retreaver.com/rtbs.json?key=YOUR_POSTBACK_KEY&caller_number=17195551234&caller_zip=90210"

The reservation keeps caller_zip=90210 even if the phone number would normally parse to a different zip, because RTB values are applied before caller-number inference.

Example — geo tags without zip:

curl -X POST "https://rtb.retreaver.com/rtbs.json?key=YOUR_POSTBACK_KEY&caller_number=17195551234&geo=us-ca"

Adds a California state geo tag. Combine with caller_zip when you need both.

2. Data Writing request

The Data Writing API lets you attach tags to a caller before they connect (or during the call), keyed by caller number or call UUID.

Whitelisted keys (same as RTB): geo, caller_zip. Other keys are stored with your affiliate/postback prefix.

How it flows:

1. Send tags — POST to the Data Writing endpoint with the caller's phone number (or call UUID) and the geo you want (caller_zip, geo, etc.).
2. Caller connects — when that number calls in, Retreaver matches your data to the call.
3. Applied before routing — your tags are on the call before carrier or Caller Number geo can fill in anything still blank.

Example — set zip before the caller dials:

curl -X POST "https://retreaverdata.com/data_writing?key=YOUR_KEY&caller_number=17195551234&caller_zip=33172"

When the call comes in, 33172 is on the call before carrier or phone inference runs.

3. Caller Number geo information

Open a campaign → Toggles tab → Geo Data Handling card. Use Caller Number geo information defaults to on.

Use geo location tags extracted from the caller number (country, state, city, zip code) unless already supplied via an RTB Inbound Request, a Data Writing request, or extracted from the carrier (see Use carrier geo information in the next section).

When on: when the call comes in, Retreaver parses the caller's phone number and may set city, state, country, zip, and geo tags such as us, 719, us-co.

When off: no phone-derived geo fields or tags are added. Carrier geo can still apply if Use carrier geo information is on.

Example — disable Caller Number geo only:

1. Turn off Use Caller Number geo information.
2. Leave Use carrier geo information on.

RTB reservations without caller_zip get no phone-derived zip or geo tags, but when the call comes in it can still receive city/state/country from the carrier.

Example — disable both toggles:

Turn off both Use Caller Number geo information and Use carrier geo information. Only geo you send explicitly (RTB, Data Writing, IVR, webhook responses, ZIP prompt) will appear on the call.

On an RTB Inbound Request (before the caller dials), Caller Number geo fills in after any values you sent on the request. Carrier geo does not apply until the caller connects — see Precedence in the next section.

Example — parsed zip from the phone number:

The [caller_zip] token in webhooks uses the zip on the call, or the parsed approximate zip when none was supplied.

4. Carrier supplied geo information

Use carrier geo information is on the same Geo Data Handling card and also defaults to on.

Use geo location tags from the carrier (country, state, city, zip code) unless already supplied either via an RTB Inbound Request or via a Data Writing request.

When on: when the call comes in, inbound and click-to-call legs read carrier webhook fields (city, state, country, zip on the caller's leg) and populate any blank location fields.

When off: carrier fields are ignored. Caller Number geo can still apply if Use Caller Number geo information is on.

Example — disable carrier geo only:

1. Open the campaign → Toggles → Geo Data Handling.
2. Turn off Use carrier geo information.
3. Leave Use Caller Number geo information on.

An inbound caller dials your tracking number from +1 719 522 8888. The carrier webhook reports Denver, CO, and zip 80202. With carrier geo off, those values are ignored.

Carrier geo does not run on an RTB Inbound Request — there is no carrier webhook until the caller dials.

For some accounts, an empty zip from the carrier is treated as missing so Caller Number geo can still fill in a zip when that toggle is on.

5. Geo information appended by webhooks

Start, data-appending, and other types of webhooks can return tags in the JSON response. Retreaver applies them to the call the same way as RTB and Data Writing tags.

Retreaver IQ: Retreaver IQ by Audience Acuity is a built-in enrichment integration that can populate caller_zip and related geo on inbound calls — via a Data Append webhook for ping-first workflows. IQ-supplied geo follows the same rules as any other webhook response below.

Response formats:

{
  "retreaver": {
    "tags": [
      { "key": "geo", "value": "us-90210" },
      { "key": "caller_zip", "value": "90210" }
    ]
  }
}

Or top-level keys (except Data Writing URLs):

{
  "geo": "us-90210",
  "caller_zip": "90210"
}

Overwriting existing geo:

• When a webhook returns caller_zip or a zip-style geo value (us-xxxxx), Retreaver clears clearable geo tags (country, state, zip — not area code) and updates caller_city, caller_state, and caller_zip from the zip database.
• During waiting-room re-pings (ping round > 1), webhook tags with the same key can replace tags from an earlier ping response. Start-of-call ping round 1 uses the default append behavior.

This is independent of the carrier / Caller Number geo toggles — those only control inference at call creation. Webhook-supplied geo from pings always takes effect when returned.

caller_zip!~.+

{
  "retreaver": {
    "tags": [
      { "key": "caller_zip", "value": "90210" }
    ]
  }
}

6. ZIP prompt

Campaign Prompts can ask callers to enter a 5-digit ZIP before routing. There are two prompt types:

After ZIP entry: if you configure post-zip webhooks, they fire after a successful entry (with a brief ring while pings run) before routing continues.

Practical workflows

Key takeaways

• You control geo via RTB caller_zip / geo and Data Writing — those win over automatic inference.
• Campaign toggles independently control carrier geo and caller-number geo (both default on).
• Webhooks can add or overwrite geo during ping rounds; caller_zip / zip-style geo responses clear and replace clearable geo tags.
• caller_zip!~.+ is the tag rule for "no zip present yet" when configuring enrichment or routing.
• ZIP unless present skips when zip geo already exists; ZIP always plays regardless and overrides — when the feature is enabled for your campaign.
• Upstream calls copy geo from the parent call; toggles don't apply there.