Freshsales ad attribution, with the setup cost stated first

The setup is the longest of any CRM Attribi connects to. The won check is the most careful.

Freshsales ad attribution means reading won and qualified deals once a day over your API key, judging each deal by its own stage rather than the view it sits in, and uploading the amount in the deal's currency to your ad platforms. The cost comes first: Freshworks has no field-creation API, so you build sixteen Contact fields by hand.

How does Freshsales ad attribution work?

Freshsales ad attribution is the practice of tying a deal in Freshsales, the CRM inside Freshworks, back to the ad click that produced its contact, and sending the deal's outcome and amount to the ad platform as an offline conversion. Freshsales keeps a sale as two records: the Contact is the person, the Deal is the money, and they are tied by primary_contact_id or, failing that, the first entry in contacts_added_list. Attribi needs only these fields:

Four Freshworks CRM API endpoints do the work: GET /api/deals/filters lists your saved views, GET /api/deals/view/:id?include=contacts pages one view at the documented 25 deals a page with contacts sideloaded, and GET /api/selector/deal_stages and GET /api/selector/currencies are fetched once per run.

Which Freshsales stage counts as won?

Freshworks' deal stages help article says Won and Lost are default stages in every pipeline, a pipeline needs at least three stages including those two, admins customise the rest under Admin Settings, Deals and Pipelines, and a second pipeline is a Pro plan feature. So most accounts have one pipeline ending in Won and Lost, and a minority have several, named whatever the admin chose.

Attribi reads the stage of each deal and decides in this order:

1. Stages you have told us are won, by id, are the only won stages. Nothing else is consulted.
2. Otherwise, stage names you have told us are won are matched exactly, trimmed, case sensitive.
3. Otherwise, the won or lost designation Freshsales keeps on its own stages settles it, in both directions.
4. Otherwise, an ordinary won name such as Won or Closed Won is recognised, after anything reading as lost, rejected, cancelled or dead has been refused. Closed on its own is not a win, because Closed Lost contains the same word.

A stage that cannot be read, because the stage list did not load or the deal sits in a stage id the list does not contain, stops the whole sync. The second case is almost always a second pipeline, since the stage selector returns the default pipeline's stages.

What broke on 2026-08-07, and what does the fix ask of you?

Until 7 August 2026 the pull took the first saved view whose name contained "won" and not "lost" and treated every deal inside it as closed-won revenue. There was no per-deal check. A view named "Won and Committed" or "Likely to Win" passed, and every deal in it went to Google Ads and Meta as a purchase. Bidding was trained on money that never arrived, and nothing in the product could have told you.

The fix shipped that day (our internal register calls it G44). The view is now only a reading scope, and an unverifiable deal stops the sync before the watermark moves, so once you supply the missing setting the next run re-reads the whole window.

It also added an onboarding step. There is no stage picker in the product for Freshsales, a deliberate scope decision, so three things are set by hand with us:

• Whether the account has one pipeline. If more, the numeric ids of your won stages, which become closed_won_deal_stage_ids.
• Any won stage whose name a stranger would not read as a win, which becomes closed_won_stage_names.
• Which view to read if several have "won" in the title, which becomes closed_won_view_id. A wrong view can now only miss wins, not invent them.

Which Freshsales plan lets you create the sixteen fields?

The earlier copy on this page said the Free plan allowed twenty-five custom fields. That number is on no current Freshworks page. Freshworks' custom field limits article, re-read on 12 October 2026, lists zero custom fields of every type on Free. They begin on Growth, capped per type and per module:

Attribi needs twelve Text fields and four Text areas on the Contact module. Each is created under Admin Settings, Leads, Contacts and Accounts, on the Contact module, with the plus icon, per Freshworks' custom fields article. Freshsales prefixes a custom field's internal name with cf_, hence the names below.

The four Text areas matter: a contact write fails as a whole when one value overflows, so a short cf_mta_attribution_path would silently stop all fourteen values landing. Attribi clips the four long values at 1,300 characters before sending.

When you click Provision, nothing is created. Attribi reads GET /api/selector/contact_fields, compares the names against the sixteen, and either marks the connection ready or lists the missing names. The code carries a note to replace this with real create calls the day Freshworks publishes a stable field-creation API.

How does the API key work, and what are the limits?

There is no OAuth flow. You paste your bundle address, acme.myfreshworks.com or an older acme.freshsales.io host, and an API key. The API documentation puts the key under your profile picture, Profile Settings, API Settings, and every request carries Authorization: Token token=<your key> against https://<bundle>/crm/sales/api/.... A per-user key dies with that user's deactivation, so connect with a user the company keeps. Rotating it is a paste; settings survive when the bundle alias is unchanged.

The same documentation sets the limit at 1,000 API requests per hour per account, returning HTTP 429 past it. A daily run is the four fixed calls plus one request per page of 25 deals, so a few hundred modified deals is under thirty requests. Each pass is capped at 50 pages, and a run that hits the cap holds its watermark for up to three runs so the oldest deals are not skipped. A deal won this morning is in your ad platforms tomorrow, not within the hour.

What does the pixel-less route look like with Freshsales?

Without the Attribi script on your site, deals are still read. What changes is matching: with no first-party record of the click, Attribi falls back to the hashed email and phone on the Contact, which match less often than a click id.

The two customer-owned fields close that gap. If your form writes the ad click id into cf_mta_clickid and its parameter name, gclid, fbclid or li_fat_id, into cf_mta_clickid_type, Attribi reads the pair back whenever a deal moves and uploads with a real click id. Both must be present; one click id per contact is stored. The pixel-less setup guide covers the form side; the GCLID capture guide covers where the id gets dropped.

Phone numbers should reach Freshsales in international format, because Attribi hashes the digits as stored and a national-format number does not match on Meta. And the pull fires three stage events, a lead event the first time it meets a new contact, then qualified and closed-won, but never the visit history; see pixel-less attribution for what the script adds.

A worked example: from a won deal to a Google Ads upload

The numbers are illustrative. On 1 March a prospect clicks a Google ad for a Dubai fit-out company and submits a form that stores gclid in a hidden field. Freshsales gets a Contact with email, a mobile_number beginning +9715, cf_mta_clickid set to the GCLID and cf_mta_clickid_type set to gclid. A rep opens a Deal, amount 42,000, currency_id pointing at AED, and on 28 March drags it to Won.

At the next daily run Attribi loads the stage and currency lists, pages the saved view, and reaches the deal because its updated_at is past the watermark. The stage resolves to Won, which Freshsales designates as won. currency_id resolves to AED. The email matches no existing lead, so one is created with a synthetic touchpoint carrying the GCLID, a lead-stage event goes out for it, and the deal is mirrored into Attribi's deal ledger.

The closed-won fan-out fires with 42,000 AED. For Google Ads that is one Data Manager API event: transactionId of the lead id plus :closed_won, so a retry can never double count, conversionValue 42000, currencyCode AED, the GCLID as the ad identifier, and the hashed email and phone alongside it. Because Attribi uses the Data Manager API, the 15 June 2026 rule blocking developer tokens with no uploads between 17 December 2025 and 15 June 2026 does not apply.

One number to check first. A conversion action Attribi creates for you today carries a 30-day click-through window. Click on 1 March, win on 28 March: it counts. A deal closed on 10 April would be accepted and credited nothing. The change to 90 days is written but not live, so if deals take more than a month, map an existing action with a longer window, or read what happens when the sales cycle outlasts Google's memory.

What this route does not do

• It creates no fields. Sixteen by hand, on Growth or above.
• It has no stage or view picker. Multi-pipeline accounts and unusual won names are configured with us; until then the sync stops rather than guesses.
• A won deal with no amount, or an amount of zero, is recorded but sends no revenue conversion.
• A deal whose currency_id is not in your account's currency list has its upload withheld and retried, then skipped with a flag, never sent in a guessed currency. A multi-currency account whose deals can lack a currency needs an account default set by hand. We have not verified the currency selector on a live account; if wrong, uploads are withheld, never mislabelled.
• The qualified pass depends on a saved view whose name you type exactly. Rename it and qualified detection silently ends.
• The first run reads 30 days back. Attribi imports no Microsoft spend, so there is no Microsoft ROAS, and funnel graduation measures maturity from Google clicks only.
• If revenue already lands in Pipedrive or Zoho, connect that instead; they provision in one click.

Common questions about this connection

Can Attribi read won deals from a second Freshsales pipeline? Yes, once the won stage ids for that pipeline are configured. The stage selector returns the default pipeline's stages, so a deal elsewhere arrives with a stage id the list does not contain, and Attribi stops the sync with a message naming the setting rather than guessing. Send the ids and the window is re-read.

How many Freshsales API requests does a daily sync use? Four fixed calls, then one request per page of 25 deals in the won view, and the same for the qualified view if you named one. A few hundred modified deals is well under thirty requests.

Why did the Freshsales sync stop with a message about stage ids? A deal turned up whose stage Attribi could not read, almost always from a second pipeline, or the stage list did not load. Nothing was imported and the watermark did not move. Once the won stage ids are set, the next run picks up from where it stopped.

Does Attribi fill the Freshsales fields for contacts it did not create? Yes. In full mode Attribi finds the contact by email and updates it, or creates it if absent; in attribution-only mode it updates contacts you already hold and skips the rest. The two click id fields are never written in either mode.

Which Freshsales plan do we need before connecting? Growth or above. Freshworks lists no custom fields on Free, and Attribi's sixteen need twelve text fields and four text areas on the Contact module, inside Growth's caps of 20 and 5. Custom pipelines are a Pro feature, which is when the stage id setting becomes relevant.

The takeaway

If your sales team lives in Freshsales and your ads live in Google and Meta, sixteen fields are a fair price for a won check that guesses nothing. Start with 30 days on the Pro plan, create the fields before you connect, and the first won deal reaches your ad account the morning after it closes.