Action and system primitives
Primitive 1: the call decision
Phone number enrichment is not a generic "make the record complete" step. Use it when a human will call, a routing rule depends on phone availability, or a sales motion needs to choose between email and phone follow-up.
| Situation | Ask for | Stop if |
|---|---|---|
| SDR call list | phone, phone_status, timezone | no status field is returned |
| Executive escalation | direct phone or mobile where present | the result is only a main line |
| CRM hygiene | phone, source, last_checked | the workflow would overwrite CRM |
| Email failure fallback | phone plus existing email status | the contact identity is unclear |
Primitive 2: the conservative phone prompt
You are enriching contacts with phone data.
Input file: contacts.csv
Goal: build a small call-review list, not blast every contact.
Required output fields: phone, phone_status, phone_type_if_available, source_status, next_step.
Run 10 rows first.
Do not claim mobile coverage unless the provider explicitly returns that signal.
Mark rows as needs_review when identity is ambiguous.
After the sample, separate rows into ready_to_call, needs_review, and no_phone_found.
This gives the operator a call list they can trust instead of a column full of numbers with unknown provenance.
Primitive 3: a call-ready review table
| full_name | company | phone | phone_status | next_step |
|---|---|---|---|---|
| Ada Lovelace | Example Co | +15551230000 | valid | ready_to_call |
| Grace Hopper | Example Co | not_found | email_only |
The status column matters as much as the number. Without it, the workflow creates manual cleanup work.
How the primitives move through skills, scripts, and Workflows
Start with the Deepline skill. The skill is the primary way to ask for phone data, inspect sample rows, and decide whether a number is usable for calls or needs review.
When the sample looks right, move the same field contract into a script for repeatable batches or a Deepline Workflow for scheduled call-list refreshes, routing, and review handoffs.
For provider phone actions, use:
POST /api/v2/integrations/{toolId}/execute
Confirmed phone-oriented provider ids include datagma_search_phone_numbers, findymail_find_phone, forager_person_contacts_lookup_phone_numbers, contactout_check_phone, and ai_ark_mobile_phone_finder.
For the prebuilt waterfall alias contact_to_phone_waterfall, POST /api/v2/enrich/compile returns an enrich config. That response is not itself a play artifact and cannot be sent directly to the play check or run routes.
The CLI/SDK converts the enrich config into play source, bundles a play artifact, checks it with POST /api/v2/plays/check, and starts it with POST /api/v2/plays/run. API clients must provide generated source and a bundled artifact to check or run, or use a supported named prebuilt play reference. For customer-facing scripts, treat contact_to_phone_waterfall as a composed play-backed flow rather than an atomic provider operation.
Script pattern after the skill works
Use provider tool execution only after the skill has helped select and validate a specific phone provider action:
deepline tools execute datagma_search_phone_numbers \
--input '{"full_name":"Ada Lovelace","company":"Example Co","domain":"example.com"}'
Use deepline enrich --with for the prebuilt waterfall alias:
deepline enrich --input contacts.csv \
--with '{"alias":"phone","tool":"contact_to_phone_waterfall","payload":{"full_name":"{{full_name}}","company":"{{company}}","domain":"{{domain}}","linkedin_url":"{{linkedin_url}}"}}' \
--output contacts-with-phone.csv
The JSON object spec keeps the workflow repeatable. It names the output alias, the play-backed waterfall alias, and the payload mapping from CSV columns.
Quality check before deploying a Workflow
No no-spend generic workflow-specific test route was found for phone number enrichment. POST /api/v2/integrations/test may execute real provider paths for provider-backed cases and must not be documented as safe test validation.
For contact_to_phone_waterfall, distinguish enrich config compilation from play artifact generation. POST /api/v2/enrich/compile returns an enrich config. The CLI/SDK then generates play source and a bundled artifact that can be validated with POST /api/v2/plays/check before execution. That is workflow preflight, not a safe phone provider test.
Before a full run, inspect whether the sample separates valid, missing, and review rows cleanly. Do not scale a phone workflow if the sample cannot explain why a number is usable.
Cost and billing behavior
Keep cost language Deepline-facing. In BYOK mode, customers bring their own data-provider keys and Deepline does not add a platform fee for that mode. In managed mode, Deepline uses credit-based operation billing.
Phone enrichment can be more sensitive than basic profile enrichment because different providers and regions have different coverage. Run a small sample first, inspect output quality, and only then scale the phone number enrichment workflow.