# Zola Registry Search Scraper (`automation-lab/zola-public-couple-registry-search`) Actor

Search Zola's public couple directory by name and export event dates, registry availability, wedding website availability, and canonical page URLs.

- **URL**: https://apify.com/automation-lab/zola-public-couple-registry-search.md
- **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community)
- **Categories:** Lead generation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.32 / 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?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Zola Registry Search Scraper

Search Zola's public couple directory by name and export matched public registries, wedding websites, and displayed event dates.

Zola Registry Search Scraper turns the **Zola registry search** workflow into structured JSON, CSV, Excel, or XML records. Give it one or more surnames or full-name combinations and receive deduplicated public couple matches with canonical Zola page URLs.

The Actor uses Zola's public Find a Couple search. It does not require a Zola login, does not access private guest data, and does not scrape registry gifts or contact details.

### What does Zola Registry Search Scraper do?

The Actor:

- searches Zola's public couple lookup with every supplied name;
- returns the public owner and partner names shown by Zola;
- preserves the Zola page slug as a stable matching key;
- exports the displayed event date when available;
- reports whether a public registry is available;
- reports whether a public wedding website is available;
- builds canonical `/registry/` and `/wedding/` URLs only when Zola reports them;
- deduplicates couples found by more than one query;
- stops as soon as the requested result limit is reached.

It is designed for repeatable name-to-page resolution, not broad crawling of every Zola page.

### Who is it for?

#### Registry matching teams

Resolve names from an authorized event, gifting, or customer list to candidate public Zola pages and keep the source query beside each match.

#### Wedding service operations

Check whether a known couple has a public registry or wedding website before continuing a human-reviewed workflow.

#### Data engineers

Add structured Zola lookup results to an ETL job, spreadsheet workflow, webhook, or scheduled Apify Task.

#### Researchers

Analyze public lookup availability and displayed event dates without manually repeating searches in a browser.

A name match is not proof of identity. Review ambiguous matches before using them in a decision or outreach process.

### Why use this Actor?

Manual Zola searches are difficult to repeat consistently across a list of names. Browser copy-and-paste also loses useful provenance such as the exact query that produced a match.

This Actor provides:

- a stable input contract for batches of names;
- typed fields instead of page markup;
- one default dataset ready for exports and integrations;
- deterministic slug-based deduplication;
- bounded retries with fresh US residential sessions for transient source blocks;
- a strict maximum-result control;
- explicit empty results rather than fabricated matches.

The implementation calls only the data route used by Zola's public Find a Couple page. It does not download page images, fonts, analytics, or registry product data.

### What data can I extract?

| Field | Type | Meaning |
| --- | --- | --- |
| `searchTerm` | string | Input name query that produced this result |
| `coupleName` | string | Combined public owner and partner display names |
| `ownerName` | string or null | Public page owner name |
| `partnerName` | string or null | Public partner name when shown |
| `pageSlug` | string | Public Zola page slug |
| `eventDate` | date-time or null | Event date returned by Zola |
| `hasRegistry` | boolean | Whether Zola reports a public registry |
| `hasWeddingWebsite` | boolean | Whether Zola reports a public wedding website |
| `canonicalUrl` | URL or null | Preferred available public Zola page |
| `registryUrl` | URL or null | Public registry URL when available |
| `weddingWebsiteUrl` | URL or null | Public wedding website URL when available |
| `sourceUrl` | URL | Public Zola lookup endpoint used by the Actor |
| `searchedAt` | date-time | Time this lookup completed |

Null means Zola did not return that value or public page type for the match.

### How to search Zola registries by name

1. Open the Actor's **Input** tab.
2. Add one or more entries under **Couple names or surnames**.
3. Use a surname for broad matching or a fuller name for a narrower lookup.
4. Set **Maximum results** to control dataset size and cost.
5. Click **Start**.
6. Open the **Dataset** tab when the run succeeds.
7. Export results or connect the dataset to your workflow.

A small first run such as `Smith` with a limit of 10 is useful for checking the output shape.

### Input parameters

#### `searchTerms`

Required array of 1 to 100 strings.

Each entry must contain 2 to 100 characters. Leading, trailing, and repeated whitespace is normalized. Duplicate terms are removed before searching.

Examples:

```json
["Smith"]
```

```json
["Maddie Smith", "Johnson", "Williams"]
```

Zola currently returns at most 50 public matches per search term. Search matching is controlled by Zola and may be broad.

#### `maxItems`

Optional integer from 1 to 5,000. The default is 100.

This limit applies across all terms after slug deduplication. Once reached, later search terms are not requested.

### Example input

```json
{
  "searchTerms": [
    "Smith"
  ],
  "maxItems": 10
}
```

For batch matching:

```json
{
  "searchTerms": [
    "Smith",
    "Johnson",
    "Williams"
  ],
  "maxItems": 120
}
```

### Example output

The following shape is based on current public source behavior. Names and slug are anonymized here.

```json
{
  "searchTerm": "Smith",
  "coupleName": "Sample Smith & Example Taylor",
  "ownerName": "Sample Smith",
  "partnerName": "Example Taylor",
  "pageSlug": "sample-and-example",
  "eventDate": "2027-06-12T00:00:00.000Z",
  "hasRegistry": true,
  "hasWeddingWebsite": true,
  "canonicalUrl": "https://www.zola.com/wedding/sample-and-example",
  "registryUrl": "https://www.zola.com/registry/sample-and-example",
  "weddingWebsiteUrl": "https://www.zola.com/wedding/sample-and-example",
  "sourceUrl": "https://www.zola.com/website-nav/web-api/v1/search/couples",
  "searchedAt": "2026-09-10T12:00:00.000Z"
}
```

Results are pushed to the run's default dataset one item at a time. The overview view highlights names, availability, dates, and page links.

### How much does it cost to search Zola registries?

The Actor uses pay-per-event pricing:

- a **$0.005 one-time start fee** per run;
- a plan-dependent **item fee** for each unique public couple saved;
- no item charge for duplicates, rejected records, failed requests, or zero-result queries.

Current item prices are:

| Apify plan | Price per saved couple |
| --- | ---: |
| Free | $0.0044528 |
| Bronze | $0.003872 |
| Silver | $0.0030202 |
| Gold | $0.0023232 |
| Platinum | $0.0023232 |
| Diamond | $0.0023232 |

At the Bronze rate, 10 saved matches cost about **$0.04372** including the start fee. A 100-match run costs about **$0.39220**. Your Apify plan and the final number of unique saved rows determine the actual Actor charge.

The Actor also uses an efficient data-only request path rather than a full browser, reducing infrastructure overhead and transfer.

### Scheduling recurring registry matching

Create an Apify Task with a stable list of authorized names, then attach a daily, weekly, or monthly schedule.

A recurring workflow can:

1. run the same name list;
2. export the new dataset;
3. join rows by `pageSlug`;
4. compare `hasRegistry`, `hasWeddingWebsite`, or `eventDate` with an earlier authorized snapshot;
5. send only reviewed changes to the next internal system.

The Actor itself does not maintain history, compare runs, send alerts, or contact couples. Your workflow owns those actions.

### Spreadsheet and data-pipeline workflow

Use the Dataset export menu for CSV or Excel, or retrieve JSON through the API.

Recommended matching keys:

- use `pageSlug` as the source-specific identifier;
- retain `searchTerm` to explain how the candidate was found;
- use `canonicalUrl` as the preferred clickable page;
- keep both availability booleans instead of inferring page type from a URL;
- treat names and dates as public display data that can change.

For large lists, split runs into auditable batches and keep `maxItems` appropriate to the expected match count.

### cURL API example

Replace `<APIFY_API_TOKEN>` with your Apify API token.

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~zola-public-couple-registry-search/runs?token=<APIFY_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"searchTerms":["Smith"],"maxItems":10}'
```

To wait for completion and get dataset items:

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~zola-public-couple-registry-search/run-sync-get-dataset-items?token=<APIFY_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"searchTerms":["Smith"],"maxItems":10}'
```

Keep API tokens in secret storage rather than committed source files.

### JavaScript API example

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const input = {
    searchTerms: ['Smith', 'Johnson'],
    maxItems: 50,
};

const run = await client
    .actor('automation-lab/zola-public-couple-registry-search')
    .call(input);

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

### Python API example

```python
import os
from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor(
    "automation-lab/zola-public-couple-registry-search"
).call(run_input={
    "searchTerms": ["Smith", "Johnson"],
    "maxItems": 50,
})

items = client.dataset(run["defaultDatasetId"]).list_items().items
print(items)
```

### Use with Apify MCP

Add this Actor to Claude Code:

```bash
claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/zola-public-couple-registry-search"
```

Claude Desktop, Cursor, and VS Code can use this equivalent MCP JSON setup:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/zola-public-couple-registry-search"
    }
  }
}
```

Example prompts:

- “Run Zola Registry Search Scraper for the surname Smith and return 10 matches.”
- “Look up these authorized couple names on Zola and save at most 50 unique public pages.”
- “Show which returned matches have a registry, a wedding website, or both.”

OAuth-capable MCP clients prompt you to authenticate. Other clients can use a securely stored Apify token.

### Reliability, retries, and failure behavior

Zola blocks ordinary direct requests to this public route, so the Actor uses US residential proxy sessions.

For each query, the Actor:

1. sends one data-only request;
2. validates HTTP status, JSON content type, and the expected row shape;
3. retries transient blocks, rate limits, server errors, timeouts, or invalid upstream responses;
4. uses a fresh coherent proxy identity for each retry;
5. stops after three failed attempts and fails the run.

A valid empty response is saved as zero rows and is not retried. This distinguishes “no public match” from an upstream failure.

### Limits and source behavior

- Only public results returned by Zola's Find a Couple search are available.
- Zola controls name matching and may return broad, duplicate-looking, incomplete, or unexpected display names.
- Each source query currently returns no more than 50 matches.
- The Actor does not scan all Zola sitemaps.
- The Actor does not open or extract gifts from individual registry pages.
- The Actor does not return contact details, guest lists, addresses, RSVP data, or private account data.
- Registry and wedding website availability can change after a run.
- A public page can have a registry, a wedding website, both, or neither reported by the search response.
- `eventDate` may be null.
- Service changes or anti-automation controls can temporarily interrupt runs.

### Tips for better matches

- Start with the fullest known public name combination.
- Try a surname separately if a full name returns no result.
- Use alternate proper names or common nicknames only when you have a legitimate reason.
- Keep the result limit low when reviewing a common surname.
- Inspect `searchTerm` and both displayed names before accepting a candidate match.
- Deduplicate downstream on `pageSlug`, not display name alone.
- Schedule reasonable intervals instead of repeatedly querying unchanged names.

### Legality, responsible use, and privacy

This Actor accesses data shown by Zola's public couple-search experience. Public availability does not remove your responsibilities.

Use the Actor only when you have a lawful purpose and authority to process the names you submit. Follow Zola's terms, applicable privacy and consumer-protection laws, and your organization's retention policies.

Do not use results for harassment, stalking, discrimination, identity theft, unwanted mass outreach, or decisions that require verified identity. Minimize stored personal data, secure exports, and delete records when they are no longer needed.

The Actor is an independent automation and is not affiliated with or endorsed by Zola.

### Troubleshooting

#### My query returned zero rows

Zola may not have a public match for that spelling. Try a proper full name, a known nickname, or a surname. Check that the run log says the term completed rather than failed.

#### My common surname returned 50 rows

Fifty is the current source maximum per term. Add more of the person's name to narrow the search. The Actor does not claim complete enumeration beyond what Zola returns.

#### The run failed after retries

Review the run log for the query and final source error. Retry later if Zola was temporarily unavailable. Repeated identical runs during an outage are unlikely to help.

#### A URL is null

Zola did not report that public page type for the match. Use `hasRegistry` and `hasWeddingWebsite` rather than constructing your own URL.

#### Several queries found the same couple

Only the first occurrence is saved. Its `searchTerm` records the query that first produced the slug in that run.

### FAQ

#### Does this search all Zola registries?

No. It searches by the names you provide and returns the public matches exposed by Zola's Find a Couple route.

#### Does it require a Zola account?

No. It uses the anonymous public search experience.

#### Can it retrieve registry gift items?

No. Gift catalogs and purchased-item details are outside this Actor's scope.

#### Can I provide direct Zola URLs?

No. This product is intentionally a name-search workflow. Use `searchTerms` with a surname or full-name combination.

#### Are matches guaranteed to be the person I mean?

No. Names are not unique, and Zola controls matching. Treat results as candidates and verify them appropriately.

#### Can I monitor changes?

You can schedule the Actor and compare datasets in your own automation. The Actor does not itself store historical snapshots or send alerts.

#### What happens when no result exists?

The run succeeds with zero dataset items for that query. No item event is charged.

#### Why is a US proxy used?

The public Zola route rejects ordinary direct requests. A US residential session provides the source geography and delivery route needed for reliable public lookup.

### Related workflows

This Actor is a standalone Zola name-to-page resolver. Its dataset works with Apify schedules, webhooks, Google Sheets, Zapier, Make, and custom API pipelines.

No other Automation Lab Actor is required. A useful downstream workflow can combine these records with your own authorized event list, CRM, or change-detection process while preserving `searchTerm`, `pageSlug`, and `searchedAt` for provenance.

### Support

When reporting a problem, include:

- the run URL;
- a privacy-safe description of the input shape;
- expected versus observed item count;
- whether the issue affected all terms or one term;
- the relevant concise error message from the log.

Do not post private names, API tokens, or exported datasets in a public support message.

# Actor input Schema

## `searchTerms` (type: `array`):

Names to search in Zola's public couple directory. Use a surname or a first-and-last-name combination. Each query can return up to 50 public matches.

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

Stop after saving this many unique matching couples across all search terms.

## Actor input object example

```json
{
  "searchTerms": [
    "Smith"
  ],
  "maxItems": 10
}
```

# Actor output Schema

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

All unique public Zola couple matches saved by this run.

# 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 = {
    "searchTerms": [
        "Smith"
    ],
    "maxItems": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/zola-public-couple-registry-search").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 = {
    "searchTerms": ["Smith"],
    "maxItems": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/zola-public-couple-registry-search").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 '{
  "searchTerms": [
    "Smith"
  ],
  "maxItems": 10
}' |
apify call automation-lab/zola-public-couple-registry-search --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,automation-lab/zola-public-couple-registry-search"
        }
    }
}
```

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/Z8fyAnAKR38SgwzCm/builds/lTfLwlpqwdhegpNcX/openapi.json