Skip to content

Quick Quality Test Utility: Prepare Input CSV Files

Before joining the live 1-hour pairing session with a Modigie engineer, prospective customer teams prepare an evaluation batch of input data (< 500 records). This guide outlines the supported job types, required and optional input columns, data formatting rules, and provides downloadable sample CSV templates.

Evaluation Batch Scope

The Quick Quality Test Utility is optimized for evaluation batches of up to 500 records to empirically verify that Modigie's live Google Cloud Pub/Sub API delivers the exact same data quality observed in your Phase 1 offline diagnostic.

While the API schema allows job request JSON payloads to include multiple URLs, email addresses etc., this Quick Quality Test Utility supports only single values for each in the input CSV to keep the tests simple.

Supported Job Types & Use Cases

The Modigie real-time engine supports 5 distinct job types. In our platform:

  • Validate / Validation: Checks syntax and deliverability (e.g., whether a phone number is valid and possible in E.164 format, whether an email has valid syntax and is deliverable, or whether a URL has valid syntax).
  • Verify / Verification: Combines an attribute with live carrier signaling and intelligence signals to evaluate its real-world context (e.g., whether a contact is actively employed at a target company, whether a phone number is active and belongs to the person), returning confidence ratings and status codes.
  • Append: Adds a new attribute that was not present in the input (e.g., appending a mobile number or a LinkedIn profile URL).
  • Enrich: The overarching outcome of combining newly appended data with live verification and validation signals.

Review the descriptions below to determine which job types align with your business evaluation:

1. Enrich Mobile & Verify Employment (enrichMobile)

  • Primary Use Case: Append an active mobile or VoIP phone number to a given lead or contact. Also performs all tasks as in Verify Employment.
  • Key Outputs & Event Codes:
    • Append mobile phone number (events.appendMobile.code): Appends one active mobile or VoIP phone number ("appended", "unable_to_append"), along with carrier signaling, network activity, line type, and confidence rating scores.
    • Verify Employment (events.verifyEmployment.code): Verifies whether the contact works at the target company ("verified"), has left the company ("changed", "verified_elsewhere"), or if Modigie was "unable_to_verify". Typically includes current employer, job title, and geographic location.
    • Append LinkedIn URL (events.appendLinkedIn.code): Indicates whether the LinkedIn user profile URL was provided by client ("from_input"), appended by Modigie ("appended"), replaced ("replaced"), or "unable_to_append".
    • Email Validation: Performs syntax and deliverability validation on the individual business email.
  • Input Requirements:
    • Required Fields: firstName, lastName, company, (email OR linkedInUrl)
    • Optional Fields: recordId, contactId, middleNames, jobTitle, phoneNumber
  • Sample Template:
    sample_input_enrich_mobile.csv

2. Verify Employment (verifyEmployment)

  • Primary Use Case: Verify if a lead or contact is still employed at the target company and what the current job title is. If the person left the target company, Modigie identifies the current employer, job function, and departure date. Also performs all tasks as in Enrich LinkedIn.
  • Key Outputs & Event Codes:
    • Verify Employment (events.verifyEmployment.code):
      • "verified": Person works at the target company (typically includes current job title).
      • "changed": Person left (or is about to leave) the target company (typically includes new employer, title, and date).
      • "verified_elsewhere": Public records show no history at target company, but current employment was confidently identified.
      • "unable_to_verify": Modigie was unable to verify whether or not the person works at the target company.
    • Append LinkedIn URL (events.appendLinkedIn.code): Indicates whether the LinkedIn profile was "from_input", "appended", "replaced", or "unable_to_append".
    • Geographic Location: Returns formatted address in locationsFormattedAddress.
    • Email Validation: Validates business email syntax and deliverability (if provided in input).
  • Input Requirements:
    • Required Fields: company, (firstName + lastName OR linkedInUrl)
    • Optional Fields: recordId, contactId, middleNames, jobTitle, email, phoneNumber
  • Sample Template:
    sample_input_verify_employment.csv

3. Verify Mobile (verifyMobile)

  • Primary Use Case: Verify if the given phone number is an active mobile phone number and belongs to a given lead or contact. Modigie enriches the number with intelligence signals and performs a rating.
  • Key Outputs & Event Codes:
    • Verify mobile phone number (events.verifyMobile.code):
      • "good_mobile": Verified phone number is possible, valid, an active mobile, and belongs to the given person.
      • "no_good_mobile": Number does not meet all criteria (disconnected, low activity, landline/special line type, or does not belong to person).
      • "unable_to_verify": Modigie was unable to rate the phone number.
    • Granular Rating Scores: Overall score, numberActivity (carrier network activity score and code), and numberNameMatch (contact ownership score and code).
    • Phone Classification & Syntax Validation: Line type (mobile, voip, fixedLine) and syntax indicators (isValid, isPossible, E.164 format).
    • Corroborating URL Validation: Syntax validation of LinkedIn profile URL (if provided as input).
  • Input Requirements:
    • Required Fields: firstName, lastName, phoneNumber (E.164 format, e.g. +12025550100)
    • Optional Fields: recordId, contactId, middleNames, company, jobTitle, email, linkedInUrl
  • Sample Template:
    sample_input_verify_mobile.csv

4. Enrich LinkedIn (enrichLinkedIn)

  • Primary Use Case: Append the LinkedIn user profile URL to a given lead or contact using first name, last name, individual business email, and company name.
  • Key Outputs & Event Codes:
    • Append LinkedIn URL (events.appendLinkedIn.code):
      • "appended": Modigie successfully appended the matching LinkedIn user profile URL.
      • "unable_to_append": Modigie could not append a LinkedIn user URL.
    • Email Validation: Performs syntax and deliverability validation on the provided business email.
  • Input Requirements:
    • Required Fields: firstName, lastName, company, email
    • Optional Fields: recordId, contactId, middleNames, jobTitle, phoneNumber
  • Sample Template:
    sample_input_enrich_linkedin.csv

Field Mapping Matrix

The table below summarizes required and optional fields across all 5 job types:

Job Type Required Fields Optional Fields Notes & Event Codes Sample Template
enrichMobile firstName, lastName, company, (email OR linkedInUrl) recordId, contactId, middleNames, jobTitle, phoneNumber Appends one mobile or VoIP number. Event codes: appendMobile, verifyEmployment, appendLinkedIn. CSV
verifyEmployment company, (firstName + lastName OR linkedInUrl) recordId, contactId, middleNames, jobTitle, email, phoneNumber Verifies current employer and position. Event codes: verifyEmployment, appendLinkedIn. CSV
verifyMobile firstName, lastName, phoneNumber recordId, contactId, middleNames, company, jobTitle, email, linkedInUrl Verifies mobile line activity and ownership. Event code: verifyMobile (good_mobile, no_good_mobile). CSV
enrichLinkedIn firstName, lastName, company, email recordId, contactId, middleNames, jobTitle, phoneNumber Appends LinkedIn profile URL. Event code: appendLinkedIn (appended, unable_to_append). CSV

Data Formatting & Integrity Rules

When assembling your evaluation CSV records, observe the following conventions:

1. The Omission Rule for Optional Values

Omission rule for optional values

Optional fields are only included in the API payload if a non-empty value is provided in the CSV row. If an optional field is empty ("") or missing, the payload builder omits that property entirely rather than sending null objects, empty dictionaries ({}), or empty arrays ([]).

  • Do not populate empty optional cells with dummy placeholders like "N/A", "null", "none", or whitespace.
  • Leave empty cells completely blank in your CSV.

2. Phone Number Format (E.164)

  • All phone numbers must follow the international E.164 format, consisting of a leading +, the country calling code, and the national subscriber number (e.g. +12025550100 for US/Canada, +442071838750 for UK).
  • The platform performs syntax validation to check whether the number is valid and possible for the specified country.
  • Numbers with missing country codes, local dialing prefixes (such as 011 or leading 0), or formatting punctuation (e.g., (415) 555-0123) will be normalized if possible, but numbers that fail syntax validation will be disqualified or discarded.

3. LinkedIn Profile URLs

  • Header name: Use linkedInUrl.
  • Value: Provide the complete HTTPS URL (e.g., https://www.linkedin.com/in/john-doe).
  • The platform performs syntax validation on the URL structure.

4. Middle Names (middleNames)

  • When providing middle names or initials, place the middleNames column directly between firstName and lastName in your CSV.
  • Both full middle names (e.g., Elizabeth) and initials (e.g., E.) are accepted.

5. Tracking Identifiers (contactId & recordId)

Input CSV files do not need a hardcoded requestId. Instead, the utility automatically computes a unique requestId for each record (and echoes it via modigieJobRequestId):

  • contactId (optional): The identifier of a B2B contact record in your database (e.g., Salesforce Contact ID 003...). If provided, it is attached as person.source.objectId (propertyName="contactId") and tagged on the job so it can be merged directly back into your CRM.
  • recordId (optional): Unique identifier for a single CSV row. This is especially useful for jobs like verifyMobile if you evaluate multiple phone numbers per contact which means you need to have one separate record in the CSV for each contact and mobile number combination. If provided, requestId is computed as <batchId>_<recordId>. If omitted, requestId is computed as <batchId>_<index> with a zero-padded row index (e.g. quick_test_1_01, quick_test_1_02).

Identifier Character Rules

The computed modigieJobRequestId serves as the job's idempotency key and must conform to the regex ^[a-zA-Z0-9\-._]{1,256}$:

  • Allowed characters: Alphanumeric (a-z, A-Z, 0-9), hyphens (-), periods (.), and underscores (_).
  • Disallowed characters: Spaces, slashes (/, \), and special symbols (@, #, $, %, &, ?) are strictly prohibited and will cause Modigie to discard the request with an InvalidJobIdError.

Next Step: Environment Setup

Once your input CSV file is prepared, proceed to:

Pre-Session Environment Setup to install dependencies and download the utility scripts.