deepline-ads-audiences

Files (19)

• SKILL.md
• audit-no-double-hash.play.ts · plays/
• build-contactout-hash-pool.play.ts · plays/
• build-hash-only-audience.play.ts · plays/
• enrich-audience-waterfall.play.ts · plays/
• evaluate-leadmagic-personal-email.play.ts · plays/
• evaluate-personal-email-provider.play.ts · plays/
• report-google-coverage-lift.play.ts · plays/
• audience-hash.ts · plays/shared/
• upload-facebook-google-hash-only-audience.play.ts · plays/
• upload-google-hash-only-audience.play.ts · plays/
• enrich-and-upload-facebook-google.md · recipes/
• max-coverage-audience.md · recipes/
• sample-abm-segment-example.md · recipes/
• audience-basics.md · shared/
• contactout-hash-pool.md · shared/
• meta-connection.md · shared/
• upload-failure-modes.md · shared/
• skill-metadata.json

SKILL.md (first lines)

# Deepline Ads Audiences

## Quick Start

```bash
npm install -g deepline
deepline -h
```

## CLI resolution

Run `deepline` when it is available. If the shell reports that command is missing, use `<workspace-root>/.deepline/runtime/bin/deepline` (or the npm-created `.cmd` shim on Windows). If neither exists, follow `https://code.deepline.com/INSTALL.md` to set up Deepline.

Build high-quality ABM paid ads audiences from first-party customer or prospect lists. This skill is for paid ads audience upload and evaluation, not outbound.

Names in this skill are starting hints. Run `deepline search "contact list -> ad platform custom audience" --type tools` and `deepline describe <tool_id>` before executing because tool names and payload shapes can change. Tool search takes a task: one sentence stating the input you have -> the result you need, not keywords. There is no `--prefix` flag.

## Before You Start

Match the request to a row in the decision matrix and read the linked file before acting. This skill is not for cold outbound, sequencing, or copywriting: personal emails here are used to improve paid ads matching, not to contact people directly.

## Decision Matrix

| User says                                                                                                                                                   | Do this                                                                      | Read                                                      |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------- |
| "max coverage", "highest match rate", "maximum match rate", "keep increasing coverage", "get to 75% coverage", exhaust LinkedIn/personal-email/hash options | Run the explicit max-coverage ladder with budget gates.                      | `recipes/max-coverage-audience.md`                        |
| `/deepline-ads-audience`, "enrich and upload to FB/Google"                                                                                                  | Run the full paid ads audience recipe.                                       | `recipes/enrich-and-upload-facebook-google.md`            |
| "sample ABM segment", "do the example workflow"                                                                                                             | Follow the reusable high-priority ABM segment recipe.                        | `recipes/sample-abm-segment-example.md`                   |
| "use ContactOut hashes", "hashed identifiers", "LinkedIn URLs to hashes"                                                                                    | Plan a bulk pass beside the ladder, not a waterfall step.                    | `shared/contactout-hash-pool.md`                          |
| "what is a hash", "why is my match rate low", first-time user                                                                                               | Explain the mechanic before quoting a plan.                                  | `shared/audience-basics.md`                               |
| encoded/internal-identifier LinkedIn URLs (`/in/ACwAA…`), "API rejected my LinkedIn URLs", "convert LinkedIn URLs"                                          | Normalize `person_linkedin_url` before upload: drop encoded, recover vanity. | Step 4 → "Normalize LinkedIn URLs" (this file)            |
| "Make sure hashes are not double hashed"                                                                                                                    | Run the no-double-hash audit play before upload.                             | `plays/audit-no-double-hash.play.ts`                      |
| "enrich this list", "buy personal emails/hashes", "run the ladder"                                                                                          | Run the waterfall. Each layer only sees rows still missing a hash.           | `plays/enrich-audience-waterfall.play.ts`                 |
| "Compare enriched versus unenriched"                                                                                                                        | Build both hash-only datasets and report lift.                               | `plays/enrich-audience-waterfall.play.ts`                 |
| "include phone numbers", "add phones"                                                                                                                       | Hash existing phones digits-only with country code.                          | `shared/upload-failure-modes.md`                          |
| "what was the match rate", "did it match"                                                                                                                   | Read `contactIdInfo.matchRatePercentage`, not the range enum.                | `shared/upload-failure-modes.md`                          |
| "put it in a sheet", "customer will upload"                                                                                                                 | Publish the validated file to Sheets; verify by row count.                   | `shared/upload-failure-modes.md`                          |
| "connect Meta", "Meta not connected", "(#100)", "business_management"                                                                                       | Connect Meta with a system user token; Meta login is not offered.            | `shared/meta-connection.md`                               |
| "upload keeps failing", "422", "audience is locked"                                                                                                         | Meta locks on write. Send the audience in one call.                          | `shared/upload-failure-modes.md`                          |
| "Upload to Google"                                                                                                                                          | Validate hash-only rows, create Google audience, sync, readback.             | `plays/upload-google-hash-only-audience.play.ts`          |
| "Upload to Facebook and Google", "upload to FB/Google", "Meta + GAds"                                                                                       | Validate once, then upload to Google and Meta.                               | `plays/upload-facebook-google-hash-only-audience.play.ts` |

## Default Workflow

1. Confirm rights, use case, and geography.
2. Discover uploadable ad accounts.
3. Build baseline and enriched audience objects.
4. Validate identifiers and expected match-rate lift.
5. Create separate platform audiences.
6. Upload rows.
7. Check status and report IDs, uploaded counts, invalid rows, and current build state.

## Ask about suppression before targeting

Ask explicitly for the suppression list: the people who should never see the ad (current customers, closed-lost accounts, active opportunities, employees, recent converters). Users rarely volunteer it, and a list that was never built or silently failed to sync spends budget on people who already bought.

- When unsure whether someone belongs on it, include them. An extra suppressed person costs a few unserved impressions; a missing one costs real money and can annoy a customer.
- Enrich it with the same ladder. Suppression matches on the same identifiers as targeting, so a work-email-only suppression list suppresses almost nobody.

## Expect different lift per platform

Set this expectation before spending: Meta gains the most from personal-email enrichment, because people register there with personal addresses. Google gains less, since a Workspace address is already a Google account and often matches from the baseline. A modest Google result is the expected shape, not a failed run.

## Explain the shape before you spend

Before running the ladder, state the mechanic in one or two sentences so the user can judge the plan rather than approve it blindly:

> Ad platforms can only match people on identifiers those people gave the platform. Your CRM holds work emails; almost nobody signs up to Meta with a work address. These layers buy the personal identifiers that do match, cheapest first.

Say what each layer costs in Deepline credits and what it is expected to add, then ask for approval before the first paid layer. Point first-time users, or anyone who asks, to `shared/audience-basics.md` for what a hash is and why it is safe to send.

## Coverage Modes

Choose the coverage mode before spending credits and record it in the run notes. Never silently downgrade a `max_coverage` request to `cost_effective`: if a provider or credential is unavailable, report the gap and continue with the next approved provider rather than stopping early.

| Mode             | Use when                                                                        | Waterfall                                                                                                                                                                                                                                                                                | Stop condition                                                                                                                                |
| ---------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `cost_effective` | User asks for the default, low-cost, or first-pass enrichment.                  | Work-email baseline → Aviato personal hashes on all eligible rows → LimaData personal hashes on remaining personal-hash misses. Optionally a ContactOut bulk pass over rows that still lack a personal hash and have a LinkedIn URL, which runs beside the ladder rather than inside it. | Stop after the hash providers, report contacts still missing personal hashes, then ask before expanded fallback.                              |
| `max_coverage`   | User asks for highest match rate, max coverage, or to keep increasing coverage. | Work-email baseline → phone hashes already present → LinkedIn repair → Aviato personal hashes for all eligible rows → LimaData personal hashes → ContactOut bulk pass beside the ladder → raw personal-email waterfall → platform upload variants.                                       | Stop when no approved provider remains, budget cap is hit, marginal lift is below threshold, or rights/geo constraints block more enrichment. |

## Shareable Plays

`plays/` holds copyable play templates. Use them when the user asks for a repeatable or shareable workflow, not just a one-off CLI run. Run them with `deepline plays`; check `deepline --help` and `deepline plays --help` when the installed surface is unclear. If `deepline plays` is unavailable, stop and ask for the Deepline SDK CLI to be installed or updated instead of approximating the upload through older command paths.

| Play                                                      | Purpose                                                                                                                                                        | Input                                                                                                                                                                     |
| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `plays/build-hash-only-audience.play.ts`                  | Build baseline and enriched hash-only datasets from source CSV rows. Raw emails are normalized and hashed once. Provider hashes pass through as lowercase hex. | `{ "file": "input.csv" }`                                                                                                                                                 |
| `plays/audit-no-double-hash.play.ts`                      | Verify the final upload payload is hash-only, deduped, populated, includes provider hashes as-is, and does not contain hash-of-hash mistakes.                  | `{ "payloadFile": "upload.csv", "providerHashFile": "provider-hashes.csv", "providerHashColumns": ["aviato_hash", "limadata_hash"] }`                                     |
| `plays/build-contactout-hash-pool.play.ts`                | Batch LinkedIn URLs through ContactOut hashed identifiers into a deduped hash pool. Reports matched profiles, net-new hashes, and per-chunk results.           | `{ "file": "contacts.csv", "limit": 100 }`                                                                                                                                |
| `plays/upload-google-hash-only-audience.play.ts`          | Create a Google Customer Match list, upload hash-only rows, and read status back.                                                                              | `{ "file": "upload.csv", "account_id": "1234567890", "audience_name": "Segment enriched 2026-06-09" }`                                                                    |
| `plays/upload-facebook-google-hash-only-audience.play.ts` | Upload the same validated hash-only rows to Google and an existing Meta/Facebook Custom Audience.                                                              | `{ "file": "upload.csv", "google_account_id": "1234567890", "meta_ad_account_id": "act_123", "meta_audience_id": "456", "audience_name": "Segment enriched 2026-06-09" }` |
| `plays/report-google-coverage-lift.play.ts`               | After Google match rates populate, calculate coverage lift, estimated matched identifiers, spend efficiency, and a follow-up note.                             | Full shape in the example below.                                                                                                                                          |

Recommended sequence: build, audit, upload (Google, or Facebook and Google), then the coverage report. Before using an upload play, run account discovery from Step 2 and confirm the selected Google Ads account name and ID with the user. Run `check` before `run` for each play, pass the input from the table, and export dataset outputs after a run:

```bash
deepline plays check ./plays/build-hash-only-audience.play.ts
deepline plays run --file ./plays/build-hash-only-audience.play.ts --input '{"file":"source.csv"}' --watch

deepline plays check ./plays/audit-no-double-hash.play.ts
deepline plays run --file ./plays/audit-no-double-hash.play.ts --input '{"payloadFile":"enriched_hash_only.csv","providerHashFile":"provider_hashes.csv","providerHashColumns":["aviato_hash","limadata_hash"]}' --watch

deepline plays check ./plays/upload-google-hash-only-audience.play.ts
deepline plays run --file ./plays/upload-google-hash-only-audience.play.ts --input '{"file":"enriched_hash_only.csv","account_id":"1234567890","audience_name":"ABM enriched hash-only 2026-06-09"}' --watch

deepline plays check ./plays/upload-facebook-google-hash-only-audience.play.ts
deepline plays run --file ./plays/upload-facebook-google-hash-only-audience.play.ts --input '{"file":"enriched_hash_only.csv","audience_name":"ABM enriched hash-only 2026-06-09","google_account_id":"1234567890","meta_ad_account_id":"act_123","meta_audience_id":"456"}' --watch

deepline plays check ./plays/report-google-coverage-lift.play.ts
deepline plays run --file ./plays/report-google-coverage-lift.play.ts --input '{"account_name":"Customer Google Ads","account_id":"1234567890","segment_name":"High-priority target-account audience","source_rows":20000,"baseline":{"label":"L1 work hash-only","audience_id":"1111111111","match_rate_pct":23,"uploaded_rows":13935},"comparisons":[{"label":"L2 Lima+Aviato hash-only","audience_id":"2222222222","match_rate_pct":35,"uploaded_rows":18386,"deepline_spend_usd":51.47},{"label":"L3 all hashes only","audience_id":"3333333333","match_rate_pct":43,"uploaded_rows":24787},{"label":"L4 all hashes + details","audience_id":"4444444444","match_rate_pct":42,"uploaded_rows":24787},{"label":"L5 LeadMagic top100 fallback","audience_id":"5555555555","match_rate_pct":44,"uploaded_rows":17016},{"label":"L6 GTM LinkedIn + Lima/Aviato","audience_id":"6666666666","match_rate_pct":45,"uploaded_rows":17064}],"spend":{"low_cost_hash_usd":51.47,"contact_fallback_usd":218.37,"total_usd":269.84},"recommendation_label":"L6 GTM LinkedIn + Lima/Aviato"}' --watch

deepline runs export <run-id> --out audience-output.csv
```

## Step 1: Confirm Rights

Ask for explicit confirmation when the source data belongs to a customer workspace or third party. The minimum confirmation is:

- The source list can be used for paid ads audience creation.

From getaero-io/gtm-eng-skills, MIT.

More from getaero-io/gtm-eng-skills