Text Name and Mailing Address Parser

Turn supplied US English name/address blocks into spreadsheet-ready mail-merge rows. This name and address parser separates first and last name, street, city, state and postcode while retaining the original block and flagging uncertain fields.

For operations assistants, mailing-list owners and data-entry teams preparing recurring lists of 100–500 records. It does not find people, enrich contacts, verify deliverability or claim international accuracy. Parsing happens inside the Actor without sending successful records to an AI or address service. “Local-only” describes the parsing algorithm: when run on Apify, your supplied data is stored and processed on Apify, not on your computer.

Why use this parser?

• Repeat a deterministic transformation instead of manually copying six columns.
• Keep each original block beside its parsed fields for source cross-checking.
• Preserve input order, duplicates and leading zeroes in ZIP codes.
• Route incomplete or ambiguous rows to human review instead of silently dropping them.
• Export through the Apify dataset to Excel, CSV or JSON.

This is a formatting assistant, not an authoritative postal or identity system. Review even unflagged output before mailing.

Who is it for?

Teams preparing repeatable US English mail-merge lists from supplied digital text. Use a separate postal-validation service if deliverability is required.

Supported record layout

Each block contains a name on its first line, street and optional unit lines, then a final city/state/ZIP line:

Jane Smith
123 Example St
Springfield, IL 62704

Use a recognized two-letter US state, territory or military abbreviation. ZIP may be five digits or ZIP+4. Missing ZIP produces a review flag. Street numbers and PO Boxes are recognized; other street styles are retained but flagged. State names such as Illinois are not normalized.

Simple First Last and Last, First Middle layouts are supported. Jr, Sr, II, III and IV suffixes are recognized. Titles are removed with a flag. Multiple unseparated given/family-name tokens, organizations and household names are flagged. Cultural name structure cannot be reliably inferred from token position.

Get started

1. Prepare newline-delimited blocks using the supported layout.
2. Choose either the records array or a single text value.
3. Set the global maxItems limit if needed; the default is 500 rows.
4. Run the Actor and open its dataset.
5. Filter needsReview=true, cross-check against originalText, then export XLSX or CSV.

Do not put actual private contact details in publicly shared tasks or runs. The examples here are synthetic.

Input example

{
  "records": [
    "Jane Smith\n123 Example St\nSpringfield, IL 62704",
    "Alex\nPO Box 42\nBoston, MA"
  ],
  "maxItems": 500
}

The second record intentionally demonstrates review flags. It is still returned and charged as a processed row.

Input parameters

Parameter	Meaning
records	Array of 1–10000 nonempty strings; each string is exactly one record. Mutually exclusive with text.
text	Single text value containing explicitly separated blocks. Blank lines separate records by default (LF or CRLF).
recordSeparator	Optional case-sensitive literal separator, not a regex; 1–100 characters. Only allowed with text.
maxItems	Global output row limit, 1–10000; default 500. Zero and unlimited are not supported.

For example, {"text":"Jane Smith\n123 Example St\nSpringfield, IL 62704---Alex\nPO Box 42\nBoston, MA","recordSeparator":"---"} selects a literal separator.

Do not provide leading, trailing or repeated separators that create empty records. Such inputs fail rather than silently removing blocks. Blank lines inside a record require the records input route or a custom separator. Each block is limited to 20000 characters; the entire input to 5000000 characters. Unsupported fields and invalid combinations fail validation.

Output columns

Column	Meaning
recordIndex	One-based position in supplied blocks.
originalText	Exact source block, including its internal whitespace.
fullName	Trimmed first name line, or null if missing.
firstName, middleName, lastName, suffix	Heuristically parsed name parts; unknown parts are null.
street	Street/unit lines joined with comma-space, or null.
city, state	Parsed city and recognized uppercase state abbreviation, or null.
postcode	ZIP text preserving leading zeroes, or null; not verified.
needsReview	True when any flag exists.
flags	Array of machine-readable missing/ambiguity reasons.

Output example

{
  "recordIndex": 1,
  "originalText": "Jane Smith\n123 Example St\nSpringfield, IL 62704",
  "fullName": "Jane Smith",
  "firstName": "Jane",
  "middleName": null,
  "lastName": "Smith",
  "suffix": null,
  "street": "123 Example St",
  "city": "Springfield",
  "state": "IL",
  "postcode": "62704",
  "needsReview": false,
  "flags": []
}

needsReview=false means the formatting rules found no issue. It does not prove that a person or address exists, that the ZIP matches the city, or that mail will arrive.

Review flags and limitations

Missing fields produce missing_name, missing_first_name, missing_last_name, missing_street, missing_city, missing_state or missing_postcode. Additional reasons include single_name, ambiguous_name, ambiguous_name_split, compound_name_review, name_title_removed, unrecognized_street, ambiguous_address_lines, unrecognized_city_state_line, ambiguous_city and control_characters.

Flagged records remain in the output for human correction. No geocoding, postal validation, deduplication, international parsing, OCR, file download or file upload is performed. Paste digital text; PDFs and images must be transcribed separately. One-line comma-delimited records are not the supported layout. Never assume this product can infer record boundaries from a continuous unseparated list.

How much does it cost to parse mailing address records?

The Actor charges a one-time $0.005 start fee plus a per-row event. Initial configuration is $0.0008 per processed row on BRONZE; FREE $0.00092, SILVER $0.000624, and GOLD/PLATINUM/DIAMOND $0.00048. See the current Store pricing before use.

At BRONZE these configured examples are $0.0058 for one row, $0.085 for 100 rows and $0.405 for 500 rows. Flagged rows are processed results and incur the same item event; there is no separate charge for flags or exports. Inputs rejected before processing do not incur our start event. Platform charges and plan terms are shown by Apify.

The output limit includes incomplete rows and duplicates. Billing limits can stop earlier; logs report supplied and saved counts and whether output was truncated. Do not interpret a limited dataset as a complete input conversion.

Integrations

• Export XLSX from the dataset for Excel mail merge; format ZIP columns as text to preserve leading zeroes.
• Send JSON rows to a spreadsheet or CRM workflow, retaining original text until review is complete.
• Filter review rows into a separate approval worksheet before downstream import.
• Use Make, Zapier or an Apify webhook to process a completed run, not to assume success from a start response.

Dataset XLSX export is supplied by Apify, not an additional generated workbook stored by this Actor. Exported cells containing untrusted text must be handled safely by downstream spreadsheet software; do not enable formulas/macros from supplied data.

API usage

Use the official Apify client or HTTP API. Keep tokens in environment variables.

curl -X POST \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H 'Content-Type: application/json' \
  'https://api.apify.com/v2/acts/automation-lab~text-name-mailing-address-parser/runs' \
  --data '{"records":["Jane Smith\n123 Example St\nSpringfield, IL 62704"]}'

import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/text-name-mailing-address-parser').call({
  records: ['Jane Smith\n123 Example St\nSpringfield, IL 62704']
});
const { items } = await client.dataset(run.defaultDatasetId).listItems({ limit: 100 });
console.log(items);

import os
from apify_client import ApifyClient
client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('automation-lab/text-name-mailing-address-parser').call(
    run_input={'records': ['Jane Smith\n123 Example St\nSpringfield, IL 62704']})
rows = client.dataset(run['defaultDatasetId']).list_items(limit=100).items

MCP usage

For Claude Code:

claude mcp add --transport http apify \
  'https://mcp.apify.com?tools=automation-lab/text-name-mailing-address-parser'

For Claude Desktop, Cursor and VS Code (where remote HTTP MCP is supported):

{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/text-name-mailing-address-parser"
    }
  }
}

Authenticate using your client's supported Apify token configuration. Discover actual tool names and schemas using scoped tools/list. Actor selection also includes run/data helper tools; it does not expose exactly one tool.

Example prompt: “Parse these explicitly separated US mailing blocks once, retain the run ID, then return at most 20 rows with firstName, lastName, postcode and needsReview.”

Start once and retain run and storage IDs: they are metadata, not result rows. If still running, follow the same run with get-actor-run using bounded 2/4/8-second backoff capped at 10 seconds and a 120-second total deadline. Set client timeout above the chosen server wait plus transport margin. Recover a known run after timeout; do not restart to poll. If the run ID is unknown, report uncertainty. At deadline, report pending and stop. Terminal failures may have partial rows and must not be reported as full success.

On success, read get-dataset-items with explicit limit, offset and needed fields. Example consumer budget: pages of 20 rows, at most 100 rows or 64 KiB serialized UTF-8 result content, whichever comes first. Enforce the byte ceiling host-side before model injection; disclose omitted oversized rows/pages. If the client cannot intercept responses, do not promise a hard byte guarantee. Track source offsets, disclose partial results and continuation offset, and keep full exports outside model context. No universal token-savings claim is made; client discovery/caching behavior varies.

Legality and diagnostics

Only submit contact information you have permission to process. Follow privacy, mailing and retention obligations. Do not use this parser to infer sensitive attributes or to validate identity. Delete run data when it is no longer needed and avoid public sharing of private address lists.

Failed operations send sanitized diagnostic input, exceptions and Actor/build/run IDs to our private GlitchTip service for repair. Secret fields and URL queries are removed; the records, text and recordSeparator fields are redacted from both SDK and terminal diagnostic snapshots. Reports are retained for 30 days. Apify run input and dataset retention follow your account storage settings; delete those stores when no longer needed. There is no independent contact-list cache or external enrichment provider. For help, open an issue on the Actor's Apify page without sharing private address lists publicly.

FAQ and troubleshooting

Why are names flagged? Token order alone cannot distinguish middle names from compound family names. Review the original; comma-leading family-name form reduces this uncertainty.

Why is state null? The parser expects a recognized two-letter US abbreviation on the final line. Full state names and foreign formats are not silently converted.

Why did the run fail? Check mutually exclusive input fields, empty blocks, separators, character caps and maxItems. Runtime validation is stricter than the editor's individual field checks.

Can I get a ready Excel file? Export the dataset as XLSX. Human review is still required; there is no bespoke formatted workbook or guaranteed postal accuracy.

Can I schedule repeated input? Yes, using Apify scheduling, but the Actor does not fetch changed files or monitor people. Update supplied text yourself and compare datasets downstream.

Related Actors

For cleaning already-tabular spreadsheet rows rather than parsing text blocks, see CSV & Excel Data Quality Cleaner. This parser remains a standalone deterministic text-preparation step; it does not call the related Actor automatically.