Geo Data Handling

Caller location in Retreaver — country, state, city, and zip — is stored as geo tags on the call and drives routing. Those values can come from several places: you can send them explicitly on an RTB Inbound Request or Data Writing request, Retreaver can infer them from the carrier or the caller's phone number (each controlled by a campaign toggle), callers can enter a ZIP in the IVR, or a webhook response can add or replace them while the call is still in progress.

This guide explains each source, the order they apply, how to turn inference on or off per campaign, and how ZIP prompts and webhook responses interact with geo that's already on the call.

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.

Example:

An inbound caller dials your tracking number from +1 719 522 8888. With Use Caller Number geo information on, Retreaver can fill in location from the phone number — for example, zip 80918 and matching geo tags — unless the call already has geo from an RTB Inbound Request, Data Writing, or the carrier.

When off: Retreaver does not look up location from the phone number. No city, state, country, zip, or phone-derived geo tags are added from the number alone. Carrier geo can still apply if Use carrier geo information is on.

Example:

An inbound caller dials your tracking number from +1 719 522 8888. With Use Caller Number geo information off, Retreaver does not add zip 80918 or other location from the phone number. Zip and geo tags stay blank unless another source supplies them — for example, the carrier if Use carrier geo information is on.

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.

Example:

An inbound caller dials your tracking number and the carrier reports Denver, CO and zip 80202. With Use carrier geo information on, Retreaver uses those carrier values to fill in any blank location fields on the call.

When off: carrier city, state, country, and zip are ignored.

Example: An inbound caller dials your tracking number and the carrier reports Denver, CO and zip 80202. With Use carrier geo information off, Retreaver ignores those values and if the call DOES NOT have any geo information from an RTB Inbound request or a Data-Writing request, it's geo information, such as caller_zip will be empty.

5. Geo information appended by webhooks

Start, data-appending and any other type of webhook can return tags in the JSON response. Retreaver will take those tags and apply them on the call right after the webhook has completed.

Overwriting existing geo

When a webhook returns caller_zip or a zip-style geo value (us-xxxxx), Retreaver replaces the existing geo tags on the call (country, city, state, zip) with the ones returned from the webhook.

[!INFO] 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.

Example:

Your call already has caller_zip=33172 from Data Writing. A Data Append webhook (including Retreaver IQ) returns caller_zip=90210. Retreaver updates the call’s zip to 90210 and replaces its geo tags with the matching geo for 90210.

Opting out of overwriting existing geo information

Sometimes you don't want the geo information data to be overwritten by new geo information from webhooks. In that case you can opt out of that behavior by simply not firing the webhook in the first place.

Example — webhook that only enriches calls missing zip:

You want a start webhook to run enrichment only when the call has no zip yet — e.g. skip when RTB already sent caller_zip.

Configure the webhook timer's tag rules (or the buyer's forward tags, depending on your setup) with:

caller_zip!~.+

This means “the call does not have a caller_zip tag with any value yet.”

Pair that rule with a webhook response that returns geo information, so:

• calls that already have zip from RTB or Data Writing won't match caller_zip!~.+ and won't be sent to that enrichment path.
• calls without zip will match and receive the webhook's geo.

6. ZIP prompt

Campaign Prompts can ask US callers to enter a 5-digit ZIP before routing. Two prompt types:

ZIP code entry — unless already present

Prompt action: ZIP code entry — unless already present

When it plays: the caller is US-based and the call has no geo tag matching us-xxxxx (no zip geo tag yet).

When it skips: RTB, Data Writing, carrier, caller-number, or an earlier webhook already left a zip geo tag on the call.

Use this when you only need to collect zip from callers who didn't provide it upstream.

ZIP code entry — always

Prompt action: ZIP code entry — always

When it plays: every US caller who has not yet completed this campaign's "always" ZIP IVR in the current flow — even if zip geo is already on the call from RTB, Data Writing, carrier, or phone parsing.

When enabled: requires the ZIP IVR always feature for your campaign (contact Retreaver support or your account manager to enable).

Overrides existing geo: a valid 5-digit entry calls the same set_zip path as caller_zip / geo:us-xxxxx — clearable geo tags are replaced and city/state/zip columns update. If the caller enters an invalid zip, the always prompt may clear stale zip/geo from a prior override before re-prompting.

Precedence vs "unless already present": if both prompts exist and always is enabled for the campaign, always wins.

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

Publisher sends zip on RTB — don't guess over it

1. Publisher includes caller_zip=90210 on every RTB Inbound Request.
2. Leave Use Caller Number geo information and Use carrier geo information on (default).
3. Retreaver keeps 90210 from the RTB Inbound Request; caller-number parsing does not replace it.

Stop phone zip guessing, keep carrier city/state

1. Turn off Use Caller Number geo information on the Geo Data Handling card.
2. Leave Use carrier geo information on.
3. Inbound calls still get carrier city/state/country; zip and geo tags from phone parsing are not added.

Collect zip on every call for compliance

1. Ask Retreaver to enable ZIP IVR always for the campaign.
2. Add prompt ZIP code entry — always to the campaign.
3. Callers hear the ZIP prompt before routing even when RTB sent a zip — their entry replaces prior zip/geo.

Enrich only calls missing zip via start webhook

1. Add a start webhook timer with tag rule caller_zip!~.+.
2. Return caller_zip or geo:us-xxxxx in the JSON response when your enrichment service finds a zip.
3. Leave Use Caller Number geo information on as a fallback for calls the webhook doesn't match.

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.