nyne-enrichment

Enrich any person by email, phone, LinkedIn URL, or name using the Nyne Enrichment API. Returns contact info, social profiles, work history, education, and optional social media posts. Supports lite mode (3 credits), newsfeed add-on, and AI-enhanced deep search. Async with polling.

# Nyne Enrichment Skill

Enrich any person by email, phone, LinkedIn URL, or name. Returns contact info, social profiles, work history, education, and optional social media posts.

**Important:** This API is async. You POST to submit, get a `request_id`, then poll GET until complete.

## Agent Instructions

When presenting results to the user, show **all available data**. Walk through each section:

1. **Identity** — displayname, bio, location, gender
2. **Contact** — emails (work + personal + alt), phones with type
3. **Social Profiles** — LinkedIn, Twitter, GitHub, Instagram with follower counts
4. **Work History** — all organizations with title, dates, current status
5. **Education** — schools with degree, field, dates
6. **Newsfeed** (if requested) — recent posts with engagement metrics

If a field is missing from the response, it means no data was found — skip it silently.

For lite mode responses, note that only 5 fields are returned (displayname, firstname, lastname, first organization, LinkedIn URL).

## Setup

**Required environment variables:**
- `NYNE_API_KEY` — your Nyne API key
- `NYNE_API_SECRET` — your Nyne API secret

Get credentials at [https://api.nyne.ai](https://api.nyne.ai).

```bash
export NYNE_API_KEY="your-api-key"
export NYNE_API_SECRET="your-api-secret"
```

Verify they're set:
```bash
echo "Key: ${NYNE_API_KEY:0:8}... Secret: ${NYNE_API_SECRET:0:6}..."
```

## Important: JSON Handling

The API response can contain control characters in JSON string values that break `jq`. All examples use a `nyne_parse` helper that cleans and re-encodes JSON via `python3`. Define it once per session:

```bash
nyne_parse() {
  python3 -c "
import sys, json, re
raw = sys.stdin.read()
clean = re.sub(r'[\x00-\x1f]+', ' ', raw)
data = json.loads(clean)
json.dump(data, sys.stdout)
"
}
```

## Quick Start

Submit an enrichment request by email and poll until complete:

```bash
nyne_parse() {
  python3 -c "
import sys, json, re
raw = sys.stdin.read()
clean = re.sub(r'[\x00-\x1f]+', ' ', raw)
data = json.loads(clean)
json.dump(data, sys.stdout)
"
}

# Submit enrichment request
curl -s -X POST "https://api.nyne.ai/person/enrichment" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $NYNE_API_KEY" \
  -H "X-API-Secret: $NYNE_API_SECRET" \
  -d '{"email": "someone@example.com"}' | nyne_parse > /tmp/nyne_enrich.json

REQUEST_ID=$(jq -r '.data.request_id' /tmp/nyne_enrich.json)
echo "Request submitted: $REQUEST_ID"

# Poll until complete (checks every 3s, times out after 6 min)
SECONDS_WAITED=0
while [ $SECONDS_WAITED -lt 360 ]; do
  curl -s "https://api.nyne.ai/person/enrichment?request_id=$REQUEST_ID" \
    -H "X-API-Key: $NYNE_API_KEY" \
    -H "X-API-Secret: $NYNE_API_SECRET" | nyne_parse > /tmp/nyne_enrich.json
  STATUS=$(jq -r '.data.status' /tmp/nyne_enrich.json)
  echo "Status: $STATUS ($SECONDS_WAITED seconds elapsed)"
  if [ "$STATUS" = "completed" ]; then
    jq '.data.result' /tmp/nyne_enrich.json
    break
  elif [ "$STATUS" = "failed" ]; then
    echo "Enrichment failed."
    jq . /tmp/nyne_enrich.json
    break
  fi
  sleep 3
  SECONDS_WAITED=$((SECONDS_WAITED + 3))
done

if [ $SECONDS_WAITED -ge 360 ]; then
  echo "Timed out after 6 minutes. Resume polling with request_id: $REQUEST_ID"
fi
```

## Submit Enrichment (POST)

**Endpoint:** `POST https://api.nyne.ai/person/enrichment`

**Headers:**
```
Content-Type: application/json
X-API-Key: $NYNE_API_KEY
X-API-Secret: $NYNE_API_SECRET
```

### Input Parameters

At least one identifier is required.

| Parameter | Type | Description |
|-----------|------|-------------|
| `email` | string | Email address (work email preferred) |
| `phone` | string | Phone number (e.g., "+14155551234") |
| `social_media_url` | string | LinkedIn, Twitter, or GitHub URL |
| `name` | string | Full name (use with `company` or `city` to disambiguate) |
| `company` | string | Company name (helps disambiguate name lookups) |
| `city` | string | City (accepts abbreviations: SF, NYC, LA) |

**Input priority ranking:** LinkedIn URL (best) > Email (work > personal) > Phone (lowest match rate). LinkedIn + email together yields best results.

### Feature Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ai_enhanced_search` | boolean | false | AI-powered deep search for additional social profiles. Longer processing time. |
| `lite_enrich` | boolean | false | Minimal enrichment: only 5 fields, 3 credits instead of 6 |
| `newsfeed` | array | omit | Social posts to fetch: `["linkedin", "twitter", "instagram", "github", "facebook"]` or `["all"]`. Cannot mix `"all"` with specific sources. +6 credits when data found. |
| `strict_email_check` | boolean | false | Strict email validation (may return no results) |
| `callback_url` | string | omit | Webhook URL for async delivery |

### Examples

**By email:**
```bash
curl -s -X POST "https://api.nyne.ai/person/enrichment" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $NYNE_API_KEY" \
  -H "X-API-Secret: $NYNE_API_SECRET" \
  -d '{"email": "someone@example.com"}' | nyne_parse > /tmp/nyne_enrich.json

REQUEST_ID=$(jq -r '.data.request_id' /tmp/nyne_enrich.json)
echo "Request ID: $REQUEST_ID"
```

**By LinkedIn URL:**
```bash
curl -s -X POST "https://api.nyne.ai/person/enrichment" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $NYNE_API_KEY" \
  -H "X-API-Secret: $NYNE_API_SECRET" \
  -d '{"social_media_url": "https://linkedin.com/in/johndoe"}' | nyne_parse > /tmp/nyne_enrich.json

REQUEST_ID=$(jq -r '.data.request_id' /tmp/nyne_enrich.json)
```

**By name + company:**
```bash
curl -s -X POST "https://api.nyne.ai/person/enrichment" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $NYNE_API_KEY" \
  -H "X-API-Secret: $NYNE_API_SECRET" \
  -d '{"name": "Jane Smith", "company": "Acme Corp", "city": "SF"}' | nyne_parse > /tmp/nyne_enrich.json

REQUEST_ID=$(jq -r '.data.request_id' /tmp/nyne_enrich.json)
```

**With newsfeed:**
```bash
curl -s -X POST "https://api.nyne.ai/person/enrichment" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $NYNE_API_KEY" \
  -H "X-API-Secret: $NYNE_API_SECRET" \
  -d '{"email": "someone@example.com", "newsfeed": ["linkedin", "twitter"]}' | nyne_parse > /tmp/nyne_enrich.json

REQUEST_ID=$(jq -r '.data.request_id' /tmp/nyne_enrich.json)
```

**Lite mode (3 credits):**
```bash
curl -s -X POST "https://api.nyne.ai/person/enrichment" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $NYNE_API_KEY" \
  -H "X-API-Secret: $NYNE_API_SECRET" \
  -d '{"email": "someone@example.com", "lite_enrich": true}' | nyne_parse > /tmp/nyne_enrich.json

REQUEST_ID=$(jq -r '.data.request_id' /tmp/nyne_enrich.json)
```

**With AI-enhanced search:**
```bash
curl -s -X POST "https://api.nyne.ai/person/enrichment" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $NYNE_API_KEY" \
  -H "X-API-Secret: $NYNE_API_SECRET" \
  -d '{"email": "someone@example.com", "ai_enhanced_search": true}' | nyne_parse > /tmp/nyne_enrich.json

REQUEST_ID=$(jq -r '.data.request_id' /tmp/nyne_enrich.json)
```

**Submit response:**
```json
{
  "success": true,
  "data": {
    "request_id": "abc123-...",
    "status": "queued",
    "message": "Enrichment request queued. Use GET /person/enrichment?request_id=... to check status."
  }
}
```

## Poll for Results (GET)

**Endpoint:** `GET https://api.nyne.ai/person/enrichment?request_id={id}`

**Headers:** Same `X-API-Key` and `X-API-Secret` as above.

### Check status once
```bash
curl -s "https://api.nyne.ai/person/enrichment?request_id=$REQUEST_ID" \
  -H "X-API-Key: $NYNE_API_KEY" \
  -H "X-API-Secret: $NYNE_API_SECRET" | nyne_parse > /tmp/nyne_enrich.json

jq '{status: .data.status, completed: .data.completed}' /tmp/nyne_enrich.json
```

### Full polling loop

```bash
SECONDS_WAITED=0
TIMEOUT=360  # 6 minutes

while [ $SECONDS_WAITED -lt $TIMEOUT ]; do
  curl -s "https://api.nyne.ai/person/enrichment?request_id=$REQUEST_ID" \
    -H "X