What You Get

• Profile Information: Names, bios, and profile details
• Social Profiles: Links to social media profiles
• Profile Photos: Profile pictures when available
• Contact Details: Email addresses, phone numbers, and professional information when available

Use Cases

• Lead Generation: Find potential customers matching your criteria
• Recruiting: Discover candidates in specific industries or roles
• Market Research: Identify professionals in target markets
• Networking: Find people with shared interests or expertise

Pricing

• Discovery: 1 credit per result
• Enrichment: 1 additional credit per successfully enriched result (only charged when contact details are found)

Request Parameters

Parameter	Type	Required	Description
keywords	string	Yes	Keywords describing the people to find (3-500 characters). Example: "registered nurses", "software engineers", "real estate agents"
location	string	No	Geographic location to search within. Can be a state (e.g., "California", "CA"), city (e.g., "San Francisco"), or city/state (e.g., "Miami, FL"). If not specified, searches all of the US.
max_results	integer	No	Maximum number of results to return (1-100). Default: 50
callback_url	string	No	URL to receive results when processing completes

Example Request

cURL

curl -X POST "https://api.nyne.ai/api/person/discover" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-API-Secret: your_api_secret_here" \
  -d '{
    "keywords": "registered nurses",
    "location": "California"
  }'

Python

import requests

url = "https://api.nyne.ai/api/person/discover"
headers = {
    "Content-Type": "application/json",
    "X-API-Key": "your_api_key_here",
    "X-API-Secret": "your_api_secret_here"
}
data = {
    "keywords": "registered nurses",
    "location": "California"
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

JavaScript

const response = await fetch("https://api.nyne.ai/api/person/discover", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-API-Key": "your_api_key_here",
        "X-API-Secret": "your_api_secret_here"
    },
    body: JSON.stringify({
        keywords: "registered nurses",
        location: "California"
    })
});
const data = await response.json();
console.log(data);

PHP

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nyne.ai/api/person/discover");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "X-API-Key: your_api_key_here",
    "X-API-Secret: your_api_secret_here"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "keywords" => "registered nurses",
    "location" => "California"
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
print_r(json_decode($response, true));

Response (202 Accepted)

{
    "request_id": "a1b2c3d4e5f6...",
    "status": "queued",
    "message": "Person discover request queued for processing."
}

Request Parameters

Parameter	Type	Required	Description
request_id	string	Yes	The request_id returned from the POST request

Example Request

curl "https://api.nyne.ai/api/person/discover?request_id=a1b2c3d4e5f6..." \
  -H "X-API-Key: your_api_key_here" \
  -H "X-API-Secret: your_api_secret_here"

Processing Status

{
    "request_id": "a1b2c3d4e5f6...",
    "status": "discovering",
    "keywords": "registered nurses",
    "location": "California",
    "created_on": "2024-01-15T10:30:00Z"
}

Status values: pending, searching, discovering, enriching, completed, failed

Completed Response

{
    "request_id": "a1b2c3d4e5f6...",
    "status": "completed",
    "keywords": "registered nurses",
    "location": "California",
    "created_on": "2024-01-15T10:30:00Z",
    "completed_on": "2024-01-15T10:31:45Z",
    "results_count": 50,
    "results": [
        {
            "displayname": "Sarah Johnson",
            "bio": "Registered Nurse at Kaiser Permanente",
            "location": "Los Angeles, CA",
            "altemails": ["sarah.johnson@email.com"],
            "fullphone": ["555-123-4567"],
            "social_profiles": {
                "facebook": {
                    "url": "https://facebook.com/sarah.johnson",
                    "photo_url": "https://..."
                }
            }
        },
        // ... more results
    ]
}

Response with Contact Details

Results are automatically enriched with contact details when available:

{
    "request_id": "a1b2c3d4e5f6...",
    "status": "completed",
    "keywords": "registered nurses",
    "location": "California",
    "results_count": 50,
    "results": [
        {
            "displayname": "Sarah Johnson",
            "first_name": "Sarah",
            "last_name": "Johnson",
            "headline": "Registered Nurse at Kaiser Permanente",
            "altemails": ["sarah.johnson@email.com"],
            "fullphone": ["+1-555-0123"],
            "location": "San Francisco, CA",
            "social_profiles": {
                "facebook": {
                    "url": "https://facebook.com/sarah.johnson",
                    "photo_url": "https://..."
                },
                "linkedin": {
                    "url": "https://linkedin.com/in/sarahjohnson"
                }
            },
            "work_history": [
                {
                    "title": "Registered Nurse",
                    "company": "Kaiser Permanente",
                    "start_date": "2020-01"
                }
            ]
        },
        // ... more results
    ]
}

No Results Response

{
    "request_id": "a1b2c3d4e5f6...",
    "status": "completed",
    "keywords": "rare specialty",
    "location": "US",
    "created_on": "2024-01-15T10:30:00Z",
    "completed_on": "2024-01-15T10:31:00Z",
    "results_count": 0,
    "results": []
}

Error Response Format

{
    "error": true,
    "error_code": "missing_parameters",
    "message": "keywords parameter is required"
}

Callback Payload

{
    "request_id": "a1b2c3d4e5f6...",
    "status": "completed",
    "completed": true,
    "results_count": 50,
    "results": [ ... ]
}

Failed Callback Payload

{
    "request_id": "a1b2c3d4e5f6...",
    "status": "failed",
    "completed": false,
    "error": "Error message describing what went wrong"
}