Understanding Destinations - Complete Setup Guide

A destination is an endpoint a campaign can send a call to: a phone number, a SIP address, a number returned by the buyer's ping, a voicemail box or an agent queue. Every destination belongs to a buyer. This guide covers the destinations list, every section of the Edit Destination panel, and how to test and troubleshoot a new destination.

Where destinations live#

Sidebar: Buyers > Destinations (app.callgrid.com/destinations). The page is titled Manage Destinations.

List view#

• Header: + New Destination, a status filter with a count (for example "All (22)"), an Any buyer filter, search, Auto Refresh (60 seconds) and a Columns side panel for adding and removing columns.
• Default columns: Name, SubId, Type, Ping, Destination (the number), Buyer, Live, Hourly, Daily, Monthly, Global, Revenue, Status.
  • Type icon: a lightning bolt marks a Variable (RTB) destination, a phone marks a static phone destination.
  • Ping shows an icon when the destination has a ping configured.
  • Live, Hourly, Daily, Monthly, Global show current counts against the destination's caps.
  • Status shows an on/off light and a pause control.
• Extra columns: the Columns panel can add Min Rev and Max Dur (minimum revenue and maximum duration), as well as ID, Ping Timeout and Dial Timeout, which are off by default. Column sort persists when you navigate away and back.
• Row actions: the pencil opens the Edit Destination panel. The kebab menu holds View references, View in reports, Reset caps, Copy and Delete.

The destination status light: a green pulsing dot means active and routable; a gray dot means paused by hand; a clock means a scheduled pause is holding it or starts within 7 days (time in the tooltip); a blue pulsing dot means a concurrency cap is reached (count and limit in the tooltip); a yellow pulsing dot means an hourly, daily, monthly, global or revenue cap is reached.

Creating a destination#

1. Go to Buyers > Destinations and click + New Destination.
2. Fill in the Settings tab (sections below) and click Save Destination.
3. Reopen the destination to configure its Ping tab. The Ping tab tooltip reads "Save the destination to enable ping settings", so a ping cannot be built on an unsaved destination.

The edit panel has two tabs: Settings | Ping. The outbound request a destination sends to the buyer is its Ping (older material called this the destination webhook). Integration webhooks are a separate feature under Integrations > Webhooks.

Static or variable#

• Static destination: the number or SIP address, revenue and duration are fixed in Settings. Best for direct buyers with a negotiated rate, internal call centers and single agents. A static destination can still have a Ping, for example to check capacity or pass data before routing.
• Variable destination: Phone Type Variable, with the number (and usually the bid and duration) returned by the buyer's Ping through Field Mapping. Used for real-time bidding and buyer platforms that return a dynamic number.

If you are new to CallGrid, start with a static destination to learn the basics, then add a Variable destination when you need live bids.

• + New Destination first opens a Destination Configuration dialog ("How would you like to configure this destination?") with Variable and Static buttons. Static opens the panel on Phone Type Phone and Revenue Type Fixed; Variable opens it on Variable for both.
• Defaults on a new static destination: Dial Attempts 1, Dial Timeout 10, Timezone EST, Business Hours Always Open, Cap Type Billable, caps unlimited, Duplicate Settings Buyer Settings, Revenue Amount 0, Billable Type Duration, Duration Start Connect, Duration Type Fixed, Duration Seconds 0. Duration Seconds therefore has to be set to the buyer agreement before the destination bills correctly.
• Phone Number has a US flag picker. A leading 1 is stripped and up to 10 digits are kept, so type the ten-digit number; no +1 is needed.
• SIP URI is a sip: / sips: picker plus a user@domain box. It accepts sip:user@domain or sips:user@domain (optional :port), and pasting a full sip:... value fills both parts.
• Dial Attempts accepts 1 to 10 and is disabled for Agent Queue (the queue's Max offers applies). Dial Timeout accepts 0 to 300. Send Digits is hidden for Agent Queue and Voicemail.
• Closing an unsaved panel asks Unsaved Changes (Yes discards). Save Destination shows "Destination Created!" ("Destination Updated!" on an edit).
• The row menu also shows Schedule pause (and Set resume time on a paused destination) for users who can manage pauses. Copy asks "Are you sure you want to copy this destination?" and creates "<name> (Copy)".
• Buyers > + New Buyer opens Create Buyer ("Add a new buyer to your organization."): General (Name, Sub ID, optional), Restrict Duplicates, Enable Concurrency Caps, Enable Caps, Tag Routing Rules, Buyer Permissions. The button is Create and the toast is "Buyer Created!".

Settings tab#

Basic Information#

Capacity and Limit Settings#

Capacity Rules#

+ Add Rule creates ordered rules that add extra limits on top of the destination's Capacity and Limit Settings: a call must pass both the base limits (including schedules) and the first matching rule's limits. Rules are evaluated top to bottom, and rule filters use source tags only (SourceName, SourceId or SourceSubid). A rule without filters matches every call. If no rule matches, only the base capacity fields apply. Use rules to give one destination different caps and concurrency per source. When a rule matches sources with Contains, the limit applies to all matching sources combined. Every call must still pass the destination's base limits too.

Revenue Settings#

Minimum Revenue can be set on the campaign, a routing group and the destination, and the most specific level wins. The destination's Min Revenue Amount overrides the campaign and group for that destination. Watch for this: a $21 floor on a routing group does not stop a destination with its own $1 Min Revenue Amount from taking a $10 call. There is no source-level Minimum Revenue: the Configure source overrides drawer has no Minimum Revenue field and nothing reads a source value.

Billing and billable status are decided on Connected Call Duration, not the longer Call Duration column. See Understanding Billable vs Converted.

Tag Transformations#

Rows of Source Tag, Value and Target Tag. When a call carries the source tag value, the target tag is written, so values from different systems can be normalized before routing. Click + to add a row.

Tag Routing Rules#

Filters that decide whether this destination is eligible for a call. Controls: Add Filter, Clear All, Manage Tags. Operators include equals, not equals, contains, greater than, less than, is empty and is not empty. Click an operator badge in a group to switch between AND and OR.

Examples:

InboundStateCode equals FL, TX, SCInboundZipCode not equals 90210, 10001InboundStateCode equals CA AND SourceName equals Google Ads

Notes for filters:

• The tag dropdown hides tags that cannot exist yet at that point in the call journey, so Buyer and Destination tags and any tag produced by routing or call end are not offered here. A missing tag is expected, not a bug.
• Tag names are case sensitive; tag values are not.
• State comes from two sources that often disagree: the caller's area code (roughly 63 percent accurate) and a publisher-supplied IP or zip-derived state (roughly 85 percent). Area-code state uses a weekly-refreshed NPANXX dataset with an NPA fallback for newer area codes. If neither resolves, the state tag is empty and a destination that requires a state rejects the call.
• To prefer visitor data and fall back to inbound data, create a Tag Alias (Integrations > Tags > New Tag > Alias), for example StateCode with Alias Of tag:VisitorStateCode|tag:InboundStateCode, and filter on the alias.

Buyer-level Tag Routing Rules are evaluated before pinging, in addition to the destination's own rules.

Notes#

Collapsible free-text notes at the bottom of the Settings tab.

Ping tab#

The Ping tab is available on every destination type once the destination is saved.

Request Data#

• Ping Integration toggle and Ping Template picker for prebuilt buyer integrations.
• Method: GET, POST, PUT, PATCH, DELETE, plus the URL.
• Content Type: JSON, Form Encoded, XML (SOAP).
• Timeout: "Configure the timeout for the ping request." A source's Webhook Timeout override on the campaign Sources tab can shorten or lengthen this for pings made for that source.
• Use Static IP for requests: requests come from 3.232.249.88 and 54.160.65.103. Turn it on only when the buyer allowlists IPs.
• Headers and Body (with Beautify).

Macros available in the URL and body:

Click the code icon in the URL bar or body editor to search and insert tags.

Ping Testing#

1. Fill in the request.
2. In Ping Testing, enter values for the auto-detected Test Variables.
3. Click Run Ping and review the response before saving.

Acceptance Parsing#

"Acceptance parsing is used to determine if the ping should be accepted or rejected. If accepted, the Destination will be considered in the route decision for calls and bids."

• Parsing Type: JSON, Split, Regex, XML.
• Rows of property, operator (Equals, Not Equal To, Greater Than, Less Than) and value. Example: code Equals 1000.
• Tag values work in keys and values: data.[[tag:InboundStateCode]] checks data.CA for a response like {"data": {"CA": 2}}.

Authorization#

"Enable to authenticate against an endpoint to get an access token before sending the main ping request. The access token is injected into the main request headers." Configure the token request, Token Path (e.g. access_token), Header Name, Header Prefix and Token TTL (60 to 86400 seconds). For plain API-key or Basic auth, use the main Headers instead. The token request supports JSON and form-encoded bodies; a buyer that needs XML authentication needs a custom build.

Confirmation Ping/Post#

For buyers that require a second request after accepting:

1. Turn on Confirmation Ping/Post.
2. Set Variable Ping ID to the response property holding the ping, bid or request id. It is stored in [[tag:PingId]].
3. Enter the confirmation method, URL and body. Use [[tag:PingId]] and any other tags, including tags extracted by Value Extraction. When the buyer is another CallGrid bidding campaign the URL is https://bid.callgrid.com/api/bid/confirmation/[[tag:PingId]].
4. Optional confirmation Headers (if empty, the main ping headers are used) and confirmation Acceptance rules.

When the confirmation fires is set on the campaign Bidding tab by Send Confirmation On: Auction Won (default) or Call Won.

Value Extraction, Bid Ordering, Rejection Protection#

• Value Extraction: maps response properties to custom tags or to PingResponseId / PingResponseCode (for example a bid id and reject reason). Runs on the ping response and, when configured, the confirmation response.
• Bid Ordering: sorts an array response by payout before extracting values, so the best offer comes first.
• Rejection Protection: "Do not reject the call or bid if the webhook http status code is not 200." Protects against false rejections from network issues.

Call Recovery and failover#

Call Recovery, Failover Routing, Retry Routing Plan and Circuit Breaker are campaign settings on the Routing tab, not destination settings. Call Recovery re-routes a call when the agent hangs up before the threshold (1 to 15 seconds, up to 2 attempts) only when the call's margin meets Min. Margin Amount (0 disables the margin check). See Circuit Breaker and Retry Routing Best Practices.

Buyer sub-account view#

A buyer user with destination permissions sees two controls per destination: the pencil opens a read-only settings view with no save button, and a separate speedometer icon edits caps and concurrency. If a buyer user cannot save, have them use the speedometer icon. See Buyer and Destination Management Guide.

Best practices#

Testing protocol#

1. Configure Settings and save.
2. Build the Ping and use Run Ping until acceptance and field mapping resolve.
3. Start with a low daily cap.
4. Watch the first 10 calls in Reports > Pings and the call timeline.
5. Adjust caps, timeouts and filters.

Common configurations#

Monitoring#

• Reports > Pings by DestinationName: Accept %, Timeout %, API Failed, Min Rev and Guarded show why pings fail.
• Summary report: RPC, No Connect %, Billable %.
• A 429 returned by the buyer's endpoint is counted under API Failed in ping statistics, which can overstate real errors.

Troubleshooting#

Static vs variable quick reference#

Do it with AI#

Ask Claude or ChatGPT. Turn on the CallGrid connector (setup guides for Claude and ChatGPT), then ask: "List my destinations with their buyer and their duration."

Stuck on a step? Ask Griddy.

The connector is read only. It looks things up and reads your data. You make the changes in CallGrid.