What You Get

• Contact Information: Verified email addresses and phone numbers for each match
• Professional Details: Current job title, company, and work history
• Social Profiles: LinkedIn, Twitter, and other social media links
• AI-Powered Matching: Results are ranked by how well they match your search criteria

How It Works

Input: Describe who you're looking for in plain English (e.g., "software engineers at Fortune 500 companies in San Francisco")

Output: A list of people matching your criteria with their full contact details

Credit Breakdown by Feature

• Basic Fast Search: type: "light" = 1 credit base
• Pro Search with Emails: type: "premium" + show_emails: true = 5 + 2 credits
• Full Featured Search: type: "premium" + insights: true + show_emails: true + show_phone_numbers: true = combined credits

Recommended: Cursor-Based Pagination

The simplest and most reliable way to paginate is using the next_cursor from the response:

1. Make your initial search request with query and limit
2. Use the next_cursor from the response for subsequent requests
3. Continue until has_more is false or next_cursor is absent

Why cursor is preferred: The cursor automatically encodes your position and search context. You don't need to track offsets or remember the request_id.

Pagination Methods

1. Cursor-Based (Recommended)

Use next_cursor from the response. The cursor encodes both position and page size automatically.

The cursor remembers your page size (limit). You can override it by providing a different limit in your request.

2. Request ID + Offset (Alternative)

Use the request_id from your first response with offset to access specific positions within your results.

3. Repeat Query with Offset (Not Recommended)

You can repeat the same query with a different offset. The system will automatically find your cached results.

Example: Pagination Sequence

Note: Each request returns only the requested slice - no deduplication needed!

Using Cursor for Pagination

Initial Request

Initial Response

Pagination Request (using cursor)

Or: Pagination Request (using request_id + offset)

Cost Efficiency

Credits are only charged for new results:

• Initial request: Fetches and caches results, credits charged
• Subsequent pagination: Serves from cache, FREE
• Beyond cached range: Fetches additional results, credits charged for new results only

Example: Getting All Results

Here's how to paginate through all results efficiently:

import requests
import time

def get_all_search_results(api_key, api_secret, query, batch_size=25, max_results=1000):
    """
    Fetch all search results using cursor-based pagination.
    Only the first batch incurs credits; subsequent pages are cached (free).
    """
    all_results = []
    next_cursor = None
    total_fetched = 0

    while total_fetched < max_results:
        # Prepare request data
        if next_cursor:
            # Use cursor for subsequent requests (no query needed)
            data = {
                'cursor': next_cursor,
                'limit': batch_size
            }
        else:
            # Initial request with query
            data = {
                'query': query,
                'limit': batch_size
            }

        # Make request
        response = requests.post(
            'https://api.nyne.ai/person/search',
            headers={
                'X-API-Key': api_key,
                'X-API-Secret': api_secret,
                'Content-Type': 'application/json'
            },
            json=data
        )

        result = response.json()

        if result['data']['status'] == 'completed':
            results = result['data']['results']
            all_results.extend(results)
            total_fetched += len(results)

            # Check if there are more results
            if not result['data'].get('has_more'):
                break

            # Get cursor for next page
            next_cursor = result['data'].get('next_cursor')
            if not next_cursor:
                break

        elif result['data']['status'] == 'processing':
            # Wait for processing to complete, then retry
            time.sleep(2)
        else:
            # Error - break
            print(f"Error: {result}")
            break

    return all_results

# Usage
query = "Software engineers at Fortune 500 companies in San Francisco"
results = get_all_search_results(api_key, api_secret, query, batch_size=25)
print(f"Found {len(results)} total results")

Array Filters

These filters accept arrays of strings. Results will match if they contain any of the specified values.

Numeric Range Filters

These filters accept integer values for filtering by ranges.

Boolean Filters

These filters accept true/false values.

Exact Match Filters

These filters accept single string values for exact matching.

Example: Comprehensive Filter Usage

Validation Rules

• Array filters: Must be arrays of non-empty strings. Single string values are automatically converted to arrays. Empty arrays are ignored.
• Numeric range filters: Must be non-negative integers. If both min and max are provided, min must be less than or equal to max.
• Boolean filters: Accept true, false, 1, or 0. Invalid values are silently ignored.
• Gender filter: Must be exactly "male" or "female" (case-insensitive). Other values return an error.
• Name filters: Accept any non-empty string. Values are sanitized to prevent injection.