Nyne.ai API Login
Company APIs

Company Employees API

Return public employee profiles associated with a company, identified by a company_name, domain, or company social_media_url (supply at least one). Results come back as a results array of person-shaped objects with profile links, headlines, locations, organizations, and related fields when available. The request is queued asynchronously and returns a request_id; poll or supply a callback_url. Credits are charged only for profiles returned.

POST https://api.nyne.ai/company/employees API key

Manual credentials take precedence over your account key.

Overview

The Company Employees API returns public employee profiles associated with a company, helping teams move from account data to people-level workflows.

Best for

  • Finding employees at a company
  • Building account contact maps
  • Connecting company enrichment to person enrichment

Returns

  • Employee profile records
  • Roles and company context
  • Identifiers for person endpoints

Parameters

company_name string optional
Company name. One of company_name / domain / social_media_url is required. Max 255 chars.
domain string optional
Company domain or website hostname. Scheme, path, and www. are removed automatically. Max 255 chars.
social_media_url string optional
Company social media URL. Query strings and fragments are stripped before processing. Max 2048 chars.
max_employees integer optional
Maximum profiles to return. Range 1-500, default 10.
callback_url string optional
http(s) URL on an allowed host that receives the completed payload automatically.

Polling for the result

This endpoint is asynchronous. A successful submit returns a request_id while the job runs in the background. Poll the same path with a GET request - same authentication headers - passing the request_id as a query parameter:

Loading your API credentials...

Each poll returns the job's current status; once it is completed the payload carries the result shown under Responses. Polling an unknown or expired request_id returns 404 request_not_found.

Status Meaning
queued · processing · pending The job is still running - keep polling.
completed The job finished; the payload carries the result and completed: true.
failed Terminal - the job could not complete; the error field explains why.

Poll every few seconds at first, backing off for long-running jobs. Polling is free - status checks never burn credits.

Prefer push delivery?
Supply the optional callback_url parameter and the completed payload is POSTed to your endpoint when the job finishes - no polling required. Delivery is retried up to 5 times with exponential backoff (1s, 5s, 15s, 1m, 5m) and a 30-second timeout per attempt; respond with a 2xx status to acknowledge receipt.

Credit usage

Credits are charged based on the matched configuration. The listed cost is the per-result unit price.

Feature Credits Notes
Company Employees 1 Charged per profile returned (per-result)
No profiles 0 No employee data found never burns per-result credits
Heads up
Empty results do not burn credits.

Responses

202 Request queued - poll the status endpoint with the returned request_id
400 missing_parameters / invalid_url / invalid_domain / invalid_parameters / invalid_callback_url
401 Missing or invalid API credentials
402 insufficient_credits
403 subscription_required or ip_not_allowed
429 rate_limit_exceeded / monthly_limit_exceeded
503 service_unavailable - the API is temporarily unavailable

A successful response wraps the payload in the { success, data, timestamp } envelope (also shown live in the panel on the right):

{
  "success": true,
  "data": {
    "request_id": "94f1bf8a0d1a1f065a9b4e7fbc3df6aa_1700000123_2210",
    "status": "completed",
    "completed": true,
    "result": {
      "results": [
        {
          "profile_id": "a1b2c3d4e5f6",
          "displayname": "Jane Doe",
          "headline": "VP of Sales at Acme",
          "bio": "Sales leader focused on B2B SaaS go-to-market.",
          "address": {
            "city": "San Francisco",
            "state": "CA",
            "country": "United States"
          },
          "organizations": [
            {
              "name": "Acme",
              "title": "VP of Sales",
              "is_current": true
            }
          ],
          "websites": [
            "https://janedoe.com"
          ],
          "social_profiles": {
            "linkedin": {
              "url": "https://linkedin.com/in/janedoe"
            }
          }
        }
      ],
      "total_results": 1
    },
    "completed_on": "2026-01-15T10:35:00Z"
  },
  "timestamp": "2026-01-01T00:00:00"
}