# Nyne Person Search (via PaySponge x402)

> Nyne Person Search (via PaySponge x402) is a paid API for AI agents from api.paysponge.com, paid per call via x402, $0.02/call, status unknown (last checked 2026-09-13).

Search for people using a natural-language query, with support for pagination, contact discovery, AI insights, and profile scoring — gated by on-chain USDC micropayment.

## Facts

- Endpoint: POST https://api.paysponge.com/x402/purchase/svc_d5ymfernpzeh58gb8/person/search
- Price: $0.02/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-13
- Activations on Zero: 0
- Tags: x402, data
- Canonical page: https://www.zero.xyz/c/nyne-person-search-via-paysponge-x402-d612c508
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_qQf5byi_TD0lgb5Mmi7aC

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability nyne-person-search-via-paysponge-x402-d612c508 -d '<json body>'
```

Example prompt: Find me up to 20 premium-quality profiles of senior software engineers at Series B fintech startups in New York who are likely decision-makers — include their best business emails and AI insights about each person.

## When to prefer this

Use this endpoint when you need to find people using a natural-language description rather than structured filters alone, especially when you want contact information (emails, phones), AI-generated insights, or profile relevance scores. Prefer the premium tier for richer results; use light for faster, cheaper lookups. Use cursor or request_id continuation to paginate beyond the initial results without paying for a full re-search.

## Known failure modes

- Query missing with no cursor or request_id provided — schema validation error
- offset + limit exceeds 1000 — rejected with validation error
- Invalid cursor or request_id — returns not_found or error status
- Payment not confirmed on-chain — 402 response before results are returned
- Search still processing — status is pending/in_progress with empty results array, poll with request_id
- GET /person/search returns 404 — only POST is supported on this live endpoint

## How this service works

Search for people with a natural-language query, or continue a previous search by resubmitting a request_id or cursor. Nyne's upstream docs also describe GET /person/search polling, but the current PaySponge purchase service does not register that route and returns 404 there as of May 4, 2026. Use POST /person/search with request_id or cursor for continuation on the live x402 wrapper.

## Output

Returns a JSON object with a request_id, search status, an array of person profiles (each containing name, location, headline, bio, social profiles, emails, phone numbers, organization history, education, AI insights, and relevance score), pagination fields (has_more, next_cursor, offset, limit), and cache metadata. Results may be pending on first call if the search is still processing.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "anyOf": [
  {
   "required": [
    "query"
   ]
  },
  {
   "required": [
    "cursor"
   ]
  },
  {
   "required": [
    "request_id"
   ]
  }
 ],
 "properties": {
  "type": {
   "enum": [
    "light",
    "premium"
   ],
   "type": "string",
   "default": "premium",
   "description": "Search quality tier."
  },
  "limit": {
   "type": "integer",
   "default": 10,
   "minimum": 1,
   "description": "Maximum number of results to return."
  },
  "query": {
   "type": "string",
   "maxLength": 1000,
   "description": "Natural-language description of the people to find."
  },
  "cursor": {
   "type": "string",
   "description": "Opaque next_cursor value from an earlier response."
  },
  "offset": {
   "type": "integer",
   "minimum": 0,
   "description": "Zero-based starting position. Offset plus limit cannot exceed 1000."
  },
  "exclude": {
   "oneOf": [
    {
     "type": "string"
    },
    {
     "type": "array",
     "items": {
      "type": "string"
     }
    }
   ],
   "description": "LinkedIn usernames to exclude."
  },
  "insights": {
   "type": "boolean",
   "default": false,
   "description": "Include AI-generated insights about each result. Ignored for light searches."
  },
  "force_new": {
   "type": "boolean",
   "default": false,
   "description": "Force a new search instead of reusing cached results."
  },
  "request_id": {
   "type": "string",
   "description": "Earlier Nyne request id to continue or replay cached search results."
  },
  "show_emails": {
   "type": "boolean",
   "default": false
  },
  "callback_url": {
   "type": "string",
   "format": "uri"
  },
  "custom_filters": {
   "type": "object",
   "description": "Structured filters for precise targeting. The upstream docs reference a separate custom filter section; unlisted fields are preserved here as a free-form object.",
   "additionalProperties": true
  },
  "high_freshness": {
   "type": "boolean",
   "default": false,
   "description": "Prioritize recently updated profiles. Ignored for light searches."
  },
  "require_emails": {
   "type": "boolean",
   "default": false
  },
  "profile_scoring": {
   "type": "boolean",
   "default": false,
   "description": "Include an AI relevance score per result."
  },
  "show_phone_numbers": {
   "type": "boolean",
   "default": false
  },
  "require_phone_numbers": {
   "type": "boolean",
   "default": false
  },
  "require_phones_or_emails": {
   "type": "boolean",
   "default": false
  }
 },
 "description": "N
… (truncated)
```

## Response schema (JSON Schema)

```json
{
 "type": "object",
 "required": [
  "success",
  "data",
  "timestamp"
 ],
 "properties": {
  "data": {
   "type": "object",
   "required": [
    "request_id",
    "status"
   ],
   "properties": {
    "limit": {
     "type": "integer"
    },
    "offset": {
     "type": "integer"
    },
    "status": {
     "enum": [
      "pending",
      "queued",
      "processing",
      "finding",
      "fetching",
      "analyzing",
      "enriching",
      "gathering",
      "aggregating",
      "searching",
      "discovering",
      "running",
      "started",
      "in_progress",
      "completed",
      "complete",
      "success",
      "succeeded",
      "failed",
      "error",
      "not_found",
      "cancelled",
      "canceled",
      "timeout",
      "timed_out"
     ],
     "type": "string"
    },
    "results": {
     "type": "array",
     "items": {
      "allOf": [
       {
        "type": "object",
        "properties": {
         "bio": {
          "type": "string"
         },
         "gender": {
          "type": "string"
         },
         "headline": {
          "type": "string"
         },
         "lastname": {
          "type": "string"
         },
         "location": {
          "type": "string"
         },
         "newsfeed": {
          "type": "array",
          "items": {
           "$ref": "#/components/schemas/NewsfeedItem"
          }
         },
         "altemails": {
          "type": "array",
          "items": {
           "type": "string",
           "format": "email"
          }
         },
         "firstname": {
          "type": "string"
         },
         "fullphone": {
          "type": "array",
          "items": {
           "$ref": "#/components/schemas/PhoneEntry"
          }
         },
         "displayname": {
          "type": "string"
         },
         "probability": {
          "enum": [
           "high",
           "medium",
           "low",
           "unknown"
          ],
          "type": "string"
         },
         "schools_info": {
          "type": "array",
          "items": {
           "$ref": "#/components/schemas/Education"
          }
         },
         "organizations": {
          "type": "array",
          "items": {
           "$ref": "#/components/schemas/Organization"
          }
         },
         "social_profiles": {
          "type": "object",
          "additionalProperties": {
           "$ref": "#/components/schemas/SocialProfile"
          }
         },
         "sch
… (truncated)
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/nyne-person-search-via-paysponge-x402-d612c508/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from api.paysponge.com](https://www.zero.xyz/host/api.paysponge.com/llms.txt)