# Text Name and Mailing Address Parser (`automation-lab/text-name-mailing-address-parser`) Actor

Turn supplied US English name and mailing-address text blocks into spreadsheet-ready rows, preserving originals and flagging incomplete or ambiguous fields. No enrichment or address verification.

- **URL**: https://apify.com/automation-lab/text-name-mailing-address-parser.md
- **Developed by:** [Automation Lab](https://apify.com/automation-lab) (community)
- **Categories:** Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.48 / 1,000 item extracteds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## 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:

```text
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

```json
{
  "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

```json
{
  "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.

```bash
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"]}'
```

```javascript
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);
```

```python
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:

```bash
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):

```json
{
  "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](https://apify.com/automation-lab/csv-excel-data-quality-cleaner). This parser remains a standalone deterministic text-preparation step; it does not call the related Actor automatically.

# Changelog

This Actor's version history is a separate document: https://apify.com/automation-lab/text-name-mailing-address-parser/changelog.md

# Actor input Schema

## `records` (type: `array`):

One newline-delimited name/address block per string. Supply records OR text, never both. 1–10000 nonempty blocks; originals preserved.

## `text` (type: `string`):

Alternative to records. Blocks separated by blank lines (LF/CRLF) or literal recordSeparator. No inferred record boundaries. Empty blocks rejected. Maximum 5000000 characters total; 20000 per block.

## `recordSeparator` (type: `string`):

Only with text. Case-sensitive literal (not regex) of 1–100 characters. Omit for blank lines. Leading, trailing and repeated separators creating empty blocks are rejected.

## `maxItems` (type: `integer`):

Global row limit in original order including duplicates and incomplete records. Default 500, range 1–10000; zero/unlimited unsupported. Billing limits may stop earlier. Remaining blocks are not output or charged.

## Actor input object example

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

# Actor output Schema

## `dataset` (type: `string`):

Parsed original blocks with name and postal fields plus ambiguity flags.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "records": [
        "Jane Smith\n123 Example St\nSpringfield, IL 62704",
        "Alex\nPO Box 42\nBoston, MA"
    ],
    "maxItems": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/text-name-mailing-address-parser").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "records": [
        """Jane Smith
123 Example St
Springfield, IL 62704""",
        """Alex
PO Box 42
Boston, MA""",
    ],
    "maxItems": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/text-name-mailing-address-parser").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "records": [
    "Jane Smith\\n123 Example St\\nSpringfield, IL 62704",
    "Alex\\nPO Box 42\\nBoston, MA"
  ],
  "maxItems": 20
}' |
apify call automation-lab/text-name-mailing-address-parser --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,automation-lab/text-name-mailing-address-parser"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/95bNfd2pyDBM8v36r/builds/uJI53f2U8dbcaUbGW/openapi.json