Dievio
Key points
- Choose a supported source operation and define the integration's responsibilities.
- Map actual lead fields to the CRM schema with identity and overwrite rules.
- Persist results and reconcile failures before repeating a paid retrieval.
A lead-to-CRM sync needs more than an API request. Define which records to retrieve, how they map to the destination, what identifies an existing contact and when a record may enter an outbound workflow.
In Dievio, lead retrieval and LinkedIn profile lookup are source operations. Scheduling, CRM writes, webhook relays and sequence enrolment belong to your integration unless a native capability is separately documented.
Choose the trigger and the owner of each stage
| Pattern | Useful when | What your integration owns |
|---|---|---|
| Scheduled retrieval | A defined audience needs periodic review or delivery | Schedule, documented search requests, checkpoints and downstream updates |
| Application-triggered lookup | An approved event supplies a supported input, such as a known LinkedIn profile URL | Input validation, lookup choice and the decision to update a record |
| Application-owned relay | Validated results need to reach another tool through an event endpoint | Event format, delivery, duplicate handling and reconciliation |
Choose a named owner for retrieval, data review, CRM writes and campaign activation. A successful import should not automatically mean a contact is ready to receive a sequence.
Use the documented search contract
The public lead-search endpoint is POST https://dievio.com/api/public/search. Authenticate with a dashboard-generated API key as a Bearer token and send JSON. The current API entry point describes pagination and credit handling.
This small request illustrates the documented fields. It is a live retrieval request, so returned records consume API credits; use a local fixture when testing only your mapping code.
POST https://dievio.com/api/public/search
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
{
"job_titles": ["Founder"],
"person_location_country": ["United States"],
"max_results": 5,
"_per_page": 5,
"_page": 1
}Read returned records from preview_data. Pagination uses _page and _per_page, with response fields such as has_more and next_page. Continue with the returned numeric page information and the documented endpoint.
- Keep the filter definition and requested page size consistent within the job.
- Check the response before advancing the checkpoint.
- Stop when the documented pagination indicates no further page.
- Handle insufficient credits or a changed effective page size explicitly rather than assuming a full uninterrupted extraction.
Public API credits are separate from workspace subscription/search credits. A repeated retrieval can spend credits again, including for previously seen people. Downloading an already saved list adds no search-credit charge; it is a different operation.
Map real fields to the destination schema
Inspect a bounded response and the CRM's current property definitions before writing the transformation. Some fields are absent or null. Do not turn a missing value into a fabricated email, phone number or company relationship.
| Returned field | Salesforce Lead example | HubSpot Contact example |
|---|---|---|
first_name | FirstName | firstname |
last_name | LastName | lastname |
work_email | Email | email |
job_title | Title | jobtitle |
company | Company text field | company contact property where appropriate |
mobile_phone | MobilePhone when appropriate | mobilephone when appropriate |
linkedin_url | Verify an existing or approved custom URL field | Verify an existing or approved custom URL property |
Verify Salesforce names and types in its Lead field reference. A company-name text field is different from an Account relationship. Validate required fields, record types and custom rules in your organisation instead of assuming every record needs the same association lookup.
HubSpot contact properties and company associations are also separate concepts. Its Contacts API guide documents property names and associations. Use the property schema from your account; labels visible in a CRM screen are not always API names.
Preserve original source values during review. Normalize a phone only when you have enough information to do so correctly, and route overlong or incompatible values to an exception queue rather than silently truncating important data.
DievioYour workflow. Powered by Dievio.
Bring B2B contact search and LinkedIn enrichment into the tools you already use.
Explore Dievio APISearch contacts · Enrich profiles · Export results
{
"job_titles": ["Founder"],
"max_results": 10
}Define identity and overwrite rules before the first write
- Identity: define which stable identifiers the destination accepts and how ambiguous matches are handled.
- Field ownership: decide whether the CRM, the returned source or a reviewed manual value is authoritative.
- Missing values: specify whether null means “leave unchanged” or a deliberate clearing action.
- Conflicts: preserve the reviewed value and queue unresolved disagreements.
- Suppression: keep recipient preferences and campaign exclusions separate from contact-field enrichment.
Salesforce supports upsert by an external ID when the object and field are configured for that approach. Choose the matching strategy from the destination's documentation; do not assume an email or phone is universally sufficient to identify a person.
Build the workflow in six observable steps
- Define the audience. Use supported filters and a count preview for an initial coverage check. Counts measure matching contact records, not unique companies.
- Retrieve a bounded page. Record the job, filter definition and pagination state without logging credentials.
- Persist the result. Keep the returned payload in appropriately restricted staging storage so downstream recovery does not require a new lookup.
- Transform and review. Apply verified field maps, identity checks, exclusions and validation rules.
- Write to the CRM. Record the destination IDs and each accepted or rejected update.
- Release the approved next action. Enrol only eligible records, then checkpoint and reconcile the job.
Use the CRM field mapping guide for the separate transformation task.
Choose the recovery action from the failure
| Failure | First check | Recovery decision |
|---|---|---|
| Authentication or credit error | Key configuration, permissions and the relevant balance | Correct the cause; do not repeatedly replay the request |
| Empty or unexpected audience | Supported fields, title variants and location meaning | Review the query using the filter diagnostic workflow |
| Missing or incompatible fields | The actual response and destination property types | Fix the map or review the exception; do not invent a value |
| Duplicate CRM records | Matching keys and the recorded destination IDs | Repair identity handling before processing more records |
| Timeout with an uncertain outcome | Stored responses, destination state and job logs | Reconcile before repeating an operation that may be billable |
Follow documented retry guidance for recoverable errors and respect any response guidance from each provider. A client-side job ID or idempotent CRM write does not create a provider-side idempotency guarantee for lead retrieval.
Test the handoff before scaling
Start with fixture-based mapping tests, then a deliberately small live job. Check null values, missing names, duplicate identities, rejected writes, exhausted budgets and interrupted processing.
Track retrieved records, accepted updates, exceptions and actual billed usage separately. Retrieval time is not evidence that the contact details were freshly re-verified. Review email quality and applicable outreach requirements before campaign activation.
When the bounded workflow behaves as intended, use the documented API operations to expand the job under explicit limits and ownership.
