Legal CRM field mapping defines where each intake answer belongs, which values are allowed, and what happens when the destination rejects a write. Copy the field-dictionary structure below before configuring a connector. Then check the resulting records, including incomplete and duplicate inquiries, rather than treating a successful request as proof that intake is complete.

The sample record illustrates a design pattern. It is not a documented API payload for Clio, Lawmatics, or TeleWizard.

Build a Canonical Legal Intake Field Dictionary

Begin with a vendor-neutral definition of each fact the firm needs. Then map it to the firm’s approved Clio or Lawmatics workflow. For firms using Acuity Scheduling, keep appointment data and booking outcomes distinct from the legal CRM record. The dictionary should be versioned, owned, and reviewed whenever intake questions, practice areas, destination fields, or automations change.

Canonical field Definition and source Type / allowed values Destination and rule Required?
person.primary_name Caller-provided name for the prospective client, not automatically the caller Structured given/family or approved company path Contact or lead object; preserve caller relationship separately Yes for record creation, subject to firm exception
contact.phone Number approved for contact Normalized international format plus original display Contact phone; do not overwrite a verified number without policy One reachable channel required
contact.safe_method Prospect’s approved method and constraints Controlled values plus concise note Restricted custom field or task context Practice-dependent
inquiry.practice_area Firm-approved routing category, not a legal conclusion Controlled picklist Lead/matter practice-area field; unknown must remain explicit Yes for routed workflows
inquiry.jurisdiction Location facts the firm uses for initial routing Country/state/county or approved structure Separate from attorney conflict or eligibility decision Practice-dependent
inquiry.parties Names supplied for later human conflict procedures Repeatable related-party structure Related contacts or protected intake fields; never mark conflict-cleared According to approved branch
appointment.status Outcome of the booking attempt Booked, review-needed, unavailable, declined, failed Appointment plus explicit workflow status Yes when scheduling attempted
handoff.owner Person or queue accountable for the next action Valid destination user/team ID Task or record owner; never a display name alone Yes for unresolved outcomes

Each row also needs sensitivity, retention, validation, overwrite, provenance, and error-handling rules. “Notes” is not a suitable default destination for structured data merely because it accepts text. If the firm wants to filter, route, report, or automate from a fact, give that fact a defined field.

Map Business Events to the Right CRM Objects

Do not begin by creating a matter for every caller. Decide the lifecycle first: inquiry, prospective client, contact, lead, matter, appointment, task, note, relationship, and communication may be separate objects. The correct path depends on the destination system and the firm’s policy.

  • Contact or person: identity and reachable channels. Avoid conflating the caller with the prospective client or other related party.
  • Lead or intake matter: the potential engagement and its pipeline state. A new inquiry may belong here before attorney acceptance.
  • Matter: use only when the firm’s system and workflow intend that object; creation must not imply representation.
  • Appointment: the scheduled event, consultation type, participants, time zone, status, and booking source.
  • Task: the owned next action with a due time. “Needs follow-up” without an owner and deadline is not a handoff.
  • Note or summary: useful narrative context, but not a substitute for fields that drive routing and reporting.
  • Relationship: the connection among caller, prospect, company, family member, opposing party, referral source, or matter.

Official-documentation example: Clio’s current developer guide distinguishes a custom-field definition from a custom-field value on a specific matter or contact. It also documents that some value types are references or picklist option IDs rather than display text. That is precisely why the field map must specify the destination identifier and type—not only the label visible to staff.

Normalize Field Types, Controlled Values, and Missing Data

For every mapped field, define the input form, normalization, destination type, and missing-data behavior. Preserve the original answer when useful, but do not send unvalidated free text into a controlled field.

Data Normalize Do not do Verification
Phone Country context, normalized number, original display, contact permission state Guess country or overwrite a verified number silently Read back exact stored number and label
Date/time ISO date/time plus explicit time zone and appointment locale Send “next Tuesday at 2” as an unparsed string Display in destination calendar and participant confirmation
Picklist Approved source value mapped to valid destination option ID Send the label when the API requires an ID or invent a new option Read back both stored identifier and human label
Boolean True, false, and—where needed—unknown/not asked Turn missing into false Test all three business states
Person relationship Separate person record plus relationship type Put multiple names into one contact-name field Confirm linked records and relationship direction
Sensitive narrative Minimum approved detail, access control, provenance Copy a full transcript into every system Review permissions, rendering, and retention

“Unknown,” “not asked,” “caller declined,” and “not applicable” are different. A field map that collapses them into a blank prevents meaningful QA and can trigger the wrong automation. Define which states the destination supports and how staff will interpret them.

Write Identity and Duplicate Rules Before the Integration

Legal intake frequently involves returning prospects, existing clients, family members calling for someone else, multiple inquiries from one household, shared phone numbers, and name variations. A simple match on email or phone can merge the wrong people. Creating a new record every time creates duplicates and fragmented history.

Define a hierarchy: exact destination record ID when the conversation began from a verified record; otherwise approved combinations of normalized contact data and firm-specific review rules. If confidence is insufficient, create a review task instead of merging. Preserve the source interaction ID and idempotency key so a retry does not create a second record.

Require Business Acknowledgement, Not Just Transport Success

A successful network request proves that the destination received and processed something according to its rules. It does not prove the firm’s complete business outcome. The acknowledgement contract should record:

  • source interaction and workflow version;
  • destination system, object IDs, and timestamps;
  • fields attempted, accepted, transformed, omitted, and rejected;
  • appointment, task, relationship, or note IDs created;
  • duplicate action taken—matched, created, queued for review, or blocked;
  • retry state and idempotency key;
  • the owner and due time for every incomplete result.

For high-value fields, read the record back or verify through an independent event. A created contact with an empty practice-area field is not a complete handoff if that field controls routing. A booked calendar event is not complete if the prospect never received the approved confirmation.

Failed-Write Matrix and Ownership

Failure Safe automated response Alert must include Human owner
Authentication or permission Stop protected retries; keep source record intact Connector, account, operation, first failure, affected workflows Integration administrator
Validation / invalid option Do not coerce to a different legal or business meaning Canonical field, rejected value, destination rule, record reference Data owner
Duplicate ambiguity Queue review; do not merge automatically Candidate records and safe comparison fields Intake operations
Rate limit / temporary outage Retry with bounded backoff and idempotency Attempt count, next retry, time limit, queued volume Integration operations
Partial workflow Preserve accepted object IDs; retry only incomplete idempotent steps Completed and missing steps, dependencies, current owner Workflow owner
Semantic mismatch Quarantine or mark review-needed Expected business state versus stored state Practice-area data owner
Alert delivery failure Escalate to secondary monitored channel Original failure plus failed alert path Operations lead

Never “fix” a rejected legal-intake value by guessing. A failed jurisdiction, practice area, party relationship, or urgency field should create an owned review. Silent coercion may make the record appear complete while changing its meaning.

Use Bounded Retries and Idempotent Actions

Retries are appropriate for temporary failures, not invalid data or revoked access. Classify errors. Use an idempotency key or equivalent source-event identifier so the same intake cannot create repeated contacts, appointments, or tasks. Cap attempts and elapsed time, record each outcome, and escalate before a time-sensitive handoff becomes stale.

Design the workflow as independently verifiable steps. If the contact was created but the appointment failed, do not blindly replay the entire workflow. Resume from the known state using the confirmed contact ID. If the destination’s behavior is uncertain, stop and ask for human review instead of risking duplicate or destructive writes.

Sample Structured Handoff Record

This abbreviated vendor-neutral example shows provenance, explicit unknowns, business outcome, and acknowledgement. It is illustrative—not a claim about a specific vendor schema.

{
  "source_interaction_id": "intake-2026-09-29-00142",
  "workflow_version": "family-law-v7",
  "prospective_client": {
    "name": {"given": "Jordan", "family": "Lee"},
    "phone": {"value": "+1...", "safe_to_text": "unknown"},
    "email": {"value": "jordan@example.com", "verified": false}
  },
  "inquiry": {
    "practice_area": "family_law",
    "jurisdiction": {"state": "CA", "county": "unknown"},
    "conflict_status": "not_reviewed",
    "representation_status": "not_offered"
  },
  "next_step": {
    "type": "human_review",
    "owner_queue": "intake-review",
    "due_at": "2026-09-29T16:30:00-07:00"
  },
  "acknowledgement": {
    "contact_id": "destination-123",
    "lead_id": "destination-456",
    "fields_rejected": [],
    "verified_at": "2026-09-29T15:43:12-07:00"
  }
}

Test the Record, Failure Path, and Alert

A test call is incomplete until the downstream objects and alerts are inspected. Build a matrix that covers normal, missing, invalid, duplicate, sensitive, and failure scenarios.

  1. Happy path: new prospect, complete approved fields, eligible booking, correct owner, and clean acknowledgement.
  2. Missing optional and required fields: confirm the branch asks only necessary questions and that explicit unknowns do not trigger incorrect defaults.
  3. Duplicate candidates: returning prospect, shared household number, changed email, and existing client calling for another person.
  4. Type and value edge cases: international phone, accented name, long text, time-zone boundary, invalid picklist, and multiple related parties.
  5. Destination failures: expired permission, validation rejection, rate limit, outage, partial write, and delayed response.
  6. Recovery: verify retry count, no duplicate objects, alert content, human task, correction, and final closed-loop status.

Control Mapping Changes and Reconcile the Destination

A field map is a versioned operating contract, not a one-time spreadsheet. A CRM administrator can rename a label, replace a picklist value, make a field required, change an automation, revoke a permission, or archive an owner without changing the intake conversation. The first visible symptom may be a missing task or a record that looks complete but no longer drives the expected workflow. Assign one map owner, record each approved version, and require a targeted regression test before a destination or source change reaches production.

Change event Pre-release evidence Post-release reconciliation Rollback or response
Field identifier, type, or required state changes Updated dictionary, sample payload, validation result, and affected branch list Read back the destination field on test and controlled live records Restore the prior map or route records to the correction queue
Controlled value is added, renamed, merged, or retired Approved source-to-destination crosswalk and historical-value treatment Check for rejected values, incorrect defaults, and broken downstream filters Reinstate the supported value or explicitly transform affected records
Owner, calendar, office, or practice route changes Current destination IDs, availability rules, fallback owner, and notification test Confirm assignment, task visibility, and acknowledgement by the intended team Move unowned work to the approved fallback without creating duplicates
Permission or authorization changes Least-privilege access review and a test for every required object and action Inspect permission errors, partial writes, and stale tokens Stop unsafe retries, alert the system owner, and preserve the intake for recovery
Source questions or intake branches change New provenance, necessity, sensitivity, null, and overwrite rules Compare the captured answer, normalized value, record, and triggered outcome Revert the branch or hold the new field for human review

Reconciliation asks whether the operational outcome matches the source interaction. Select a small, defined sample by practice path and failure class. Compare the caller-approved or staff-approved source facts with the destination contact, lead or matter, related note, appointment, task, owner, and acknowledgement. Record discrepancies by field and cause. Do not use an attractive summary as proof that structured fields are correct, and do not store full transcripts merely to make testing easier if the firm’s retention and access policy does not require them.

For historical corrections, define the exact scope before running a backfill. Decide which records and version are affected, whether a newer human edit must win, how duplicates are prevented, how the change is audited, and how the result is sampled. A retry that was safe seconds after an outage may be unsafe days later because staff could have corrected or completed the record. Put aged failures into human review instead of assuming that automation still owns the truth.

Frequently Asked Questions

What is legal CRM field mapping?

It is a documented contract that maps each canonical intake fact to a destination object and field, including type, allowed values, validation, sensitivity, overwrite, acknowledgement, failure, and ownership rules.

Is a call summary enough?

No. A summary gives useful narrative context, but structured fields are needed for routing, filtering, automation, and reporting. Use both, with clear roles and minimum necessary detail.

Should every caller create a matter?

Not automatically. The firm must define its contact, lead, intake, and matter lifecycle in the destination system. Creating an object must not imply representation or completed conflict review.

Bring your field dictionary to TeleWizard when defining which intake actions the integration should perform. Review the TeleWizard options.

Official Sources

Related