<!-- AUTO-GENERATED from the capability registry — regenerate: npm run generate:registry -->

# `employees` — Orange Slice capability

> Outcome-priced capability. One price for the answer, whichever providers it took.
> Everything we expose, with prices: https://orangeslice.ai/llms.txt

Finds people at a company by job title. Billed one credit per row returned, so `--limit` is also your budget. Output field names match what `enrich` reads, so the two pipe together directly.

## Price

**$0.002 per result, minimum $0.002, up to $0.20 per call**

Billed per row returned, within the floor and ceiling above.

The price is a property of the outcome, not of the work behind it. Whichever
vendor serves this call, and whatever it costs us, the number above is the number
quoted before the run and charged after it.


## Call it

**CLI**

```bash
orangeslice search employees --company-slug stripe --title-variations "VP Sales" --limit 25

# the whole point — find, enrich, and materialise in one line:
orangeslice search employees --company-slug stripe --title-variations "VP Sales" \
  | orangeslice enrich work_email \
  | orangeslice sheets push "Stripe VPs"
```

**HTTP**

```bash
curl -X POST 'https://orangeslice.ai/api/v1/run' \
  -H 'Authorization: Bearer $ORANGESLICE_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"capability":"employees","input":{"companySlug":"<string>","limit":"<number>","linkedinUrl":"<string>"}}'
```

**SDK**

```ts
await services.company.employees({ companySlug: "…", limit: "…", linkedinUrl: "…" });
```

## Inputs

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `companySlug` | string | No | LinkedIn universal name, e.g. 'stripe'. The fastest lookup, and mutually exclusive with linkedinUrl |
| `limit` | number | No | Rows to return, 1–100 (default 25). You are billed one credit per row |
| `linkedinUrl` | string | No | Full LinkedIn company URL. Mutually exclusive with companySlug |
| `minConnections` | number | No | Minimum LinkedIn connection count |
| `onlyCurrent` | boolean | No | Current employees only (default true) |
| `searchStrategy` | string | No | 'database' (default) for volume; 'web' for leadership roles verifiable from public sources |
| `titleVariations` | string[] | No | Title keywords, e.g. ['CEO','founder']. Each becomes a filter. Required when searchStrategy is 'web' |
| `usOnly` | boolean | No | US-based only (default true) |

Inputs may also be piped as NDJSON, one JSON object per line.

## Output

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "employees": {
      "default": [],
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "firstName": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "lastName": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "fullName": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "title": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "company": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "headline": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "location": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "linkedinUrl": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "connections": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "firstName",
          "lastName",
          "fullName",
          "title",
          "company",
          "headline",
          "location",
          "linkedinUrl",
          "connections"
        ],
        "additionalProperties": false
      }
    },
    "nextPage": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ]
    },
    "totalResults": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "employees",
    "nextPage",
    "totalResults"
  ],
  "additionalProperties": false
}
```

The field that carries the answer is `employees`. It is
`null` — or empty — when nothing was found, which is how a miss is told from a
hit without knowing anything else about this entry.

## Before you run

- **Price it first.** `orangeslice search employees --dry-run` returns the
  exact dollar cost and spends nothing.
- **Large runs need approval.** Above the spend-gate threshold a run exits **7**
  until it carries a plan token, and only a dry run mints one.
- **Scopes:** enrich
- **Permitted uses:** research, outreach, export

## Exit codes

`0` ok · `2` bad input · `3` auth · `4` not found · `5` provider ·
`6` rate limited · `7` spend gate, nothing billed · `8` timeout ·
`9` a third-party account needs connecting