Dievio
Key points
- Separate the provider response from your internal record model.
- Preserve identity evidence, field meaning and explicit review states.
- Test missing values, conflicts and schema changes before bulk updates.
A lead-data schema should separate what a source returned from what your application concluded and what the destination is allowed to store. That separation makes missing fields, conflicting identities and later corrections easier to investigate.
Start with the actual source contract. A convenient internal model is useful, but it must not be presented as a provider's response or as evidence that the provider supplies every field in it.
Keep three schema layers distinct
| Layer | Contains | Ownership |
|---|---|---|
| Source envelope | The documented response, operation and retrieval context | Provider contract plus your stored request evidence |
| Internal review model | Normalized values, candidate matches and explicit review outcomes | Your application |
| Destination payload | Only approved changes using the destination's schema | Your integration under CRM ownership rules |
Keep the mapping version between layers. If a taxonomy changes, you should be able to explain how the same source observation produced a different classification.
Read the actual lead-search response
Dievio public search returns the record array in preview_data. Available contact fields include names, title, company, location and contact details where present. The request and response also carry pagination and scope fields.
Inspect the current documentation and a controlled actual response before making fields mandatory. Do not invent a universal provider contact ID, nested company object, confidence score or field-verification timestamp.
The pagination guide covers page, per_page, has_more and next_page. Those fields belong to extraction state, not the identity of a person.
Represent review state explicitly
This small example is an illustrative application record, not a Dievio API response. Its identifiers and review categories are defined by your integration.
<code>{
"application_record_id": "your-assigned-record-reference",
"source_operation": "your-stored-retrieval-reference",
"raw_title": "Acting VP Sales, EMEA",
"review_state": "needs_role_review",
"unresolved_questions": ["Confirm current responsibility"],
"mapping_version": "your-approved-map-version"
}</code>Keep unknown, excluded and accepted states distinct. An empty string is not a reliable substitute for every missing, unavailable or unreviewed value.
Store identity evidence without declaring a universal key
Email, profile URLs and company domains can help matching under the right contract. None should be assumed to identify every person or account perfectly across time and sources.
Preserve the raw identifier and any normalized candidate separately. Route ambiguous matches for review, especially before merging records or replacing a trusted company association.
A normalized search key can aid discovery without becoming the authoritative identity. The CRM hygiene guide addresses conservative matching and recovery.
Keep field meaning with the value
- Dates: distinguish source observation, retrieval, normalization and review time.
- Location: distinguish person location from company location and researched service territory.
- Scale: retain the meaning and bounds of revenue or employee bands.
- Titles: preserve qualifiers such as acting, regional and business-unit scope.
- Contact status: separate availability from independent validation and campaign eligibility.
Do not rename a retrieval date to “last verified” or a company-location value to “headquarters” without supporting evidence.
Validate changes at the schema boundary
Check required fields, types, allowed options and unknown additions. Preserve enough source evidence to investigate a rejected record without repeating paid retrieval.
Decide what happens when the provider adds an optional field or returns a null. A controlled adapter should surface meaningful contract changes rather than silently dropping critical data or making all new fields public.
Use the normalization workflow for values and the field-mapping guide for destination rules.
Test conflicts and recovery, not only complete records
Use fixtures for missing fields, competing company matches, unknown options, a protected manual edit and a repeated delivery. Confirm that the stored source, internal review outcome and destination change can be traced independently.
Keep credentials out of records and minimize duplicated contact data in diagnostics. A maintainable schema makes the next decision explicit while retaining the evidence needed to correct it.
