Overview

• Input: At least one of a company name, company domain, or company social media URL.
• Range: Request between 1 and 1,000 employee profiles per job.
• Delivery: Always asynchronous. Receive a request_id immediately, then poll or register a callback.
• Output: A results array of person-shaped objects with names, headlines, locations, organizations, profile photos, and social profile links.
• Caching: Raw source data is cached for 7 days and formatted results are stored for fast follow-up retrieval.

Authentication

Authenticate every request with your API key and secret:

X-API-Key: your_api_key_hereX-API-Secret: your_api_secret_here

Rate Limits

Company employee requests count against the following limits for your account:

• Per Minute: 60 requests
• Per Hour: 1000 requests
• Monthly: Varies by plan

Credit Usage

Credits are charged based on the number of profiles returned:

• Company Employees: 3 credits per person found

POST /company/employees

Queue a company employee lookup request.

curl -X POST https://api.nyne.ai/company/employees \
  -H "X-API-Key: your_api_key_here" \
  -H "X-API-Secret: your_api_secret_here" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Acme",
    "domain": "acme.com",
    "max_employees": 25
  }'

GET /company/employees?request_id=...

Poll for completion or retrieve cached results.

curl -X GET "https://api.nyne.ai/company/employees?request_id=94f1bf8a0d1a1f065a9b4e7fbc3df6aabbb6d828ce64fe780a5496f43b61fc73" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-API-Secret: your_api_secret_here"

Response Format

The completed payload returns a results array of person-shaped objects. Common fields include:

displayname                         // Full name
headline                            // Current headline or title line
bio                                 // Headline fallback for profile summary
address.city                        // City if available
address.state                       // State or region if available
address.country                     // Country if available
organizations[0].name               // Current organization name
organizations[0].is_current         // Always true for the current organization entry
social_profiles                     // Social profile URLs and photo metadata when available
websites[]                          // Personal website URLs when available
                    

Callbacks

If you provide a callback_url, the completed payload is sent to your endpoint automatically.

POST https://example.com/webhook/company-employees
Content-Type: application/json

{
  "request_id": "94f1bf8a0d1a1f065a9b4e7fbc3df6aabbb6d828ce64fe780a5496f43b61fc73",
  "status": "completed",
  "completed": true,
  "completed_on": "2026-04-20T21:15:19Z",
  "timestamp": "2026-04-20T21:15:19Z",
  "success": true,
  "data": {
    "company_name": "Acme",
    "domain": "acme.com",
    "max_employees": 25,
    "page": 1,
    "limit": 25,
    "total_results": 1,
    "results": [
      {
        "displayname": "Jane Doe",
        "headline": "VP of Sales at Acme"
      }
    ]
  }
}

Error Codes

• missing_parameters – None of company_name, domain, or social_media_url was supplied.
• invalid_url – The supplied company social media URL could not be processed.
• invalid_domain – The supplied company domain could not be processed.
• invalid_limit – max_employees must be between 1 and 1000.
• invalid_callback_url – callback_url is not a valid HTTP or HTTPS URL.
• subscription_required – This API is not enabled on the account.
• rate_limit_exceeded / monthly_limit_exceeded – Usage limits were exceeded.
• request_not_found – The request_id does not exist or does not belong to the authenticated API key.

Best Practices

• Use the strongest identifier you have: A clean company domain or social media URL tends to be more specific than a name by itself.
• Set a realistic limit: Start with a smaller max_employees for interactive workflows, then increase it for batch jobs.
• Prefer callbacks for larger requests: Polling works well for testing, but production integrations should supply a callback_url.
• Chain to person enrichment selectively: Use this endpoint to identify relevant profiles first, then enrich only the people you actually need.