# Person Events API
> Discover people linked to key events like fundraises, conferences, and podcasts for timely outreach
**Base URL:** `https://api.nyne.ai`
**Endpoint:** `https://api.nyne.ai/person/events`

---

## Overview
The Person Events API lets you find people who have participated in specific events such as demo days, conferences, and podcasts. All fields except event are optional, allowing flexible queries. You can search for all attendees at an event, filter by company to find which employees attended, search by role to find CTOs, founders, or other titles, or filter by geographic location. Results are generated asynchronously and provide accurate, current data.
### What You Get
- **Event Attendee Discovery:** Find people who participated in specific events, conferences, and podcasts- **Company Filtering:** Narrow results to employees of a specific company who attended- **Role-Based Search:** Filter attendees by job title such as Founder, CTO, or VP Engineering- **Industry Filtering:** Focus on attendees from specific industry sectors like Health Tech or Fintech- **Location-Based Discovery:** Find attendees from specific geographic regions- **Async Results:** Queue searches and retrieve results via polling or callback URL
## Authentication

All requests require header authentication:

```
X-API-Key: YOUR_API_KEY
X-API-Secret: YOUR_API_SECRET
```

## Rate Limits

| Limit | Value |
|-------|-------|
| Per Minute | 60 requests |
| Per Hour | 1000 requests |
| Monthly | Varies by plan |

### Response Headers

Responses from endpoints that perform rate-limit checks include both legacy and standard rate-limit headers:

| Header | Description |
|--------|-------------|
| `X-RateLimit-Limit` | Active per-minute or per-hour limit |
| `X-RateLimit-Remaining` | Remaining requests in the active window |
| `X-RateLimit-Reset` | Unix timestamp when the active window resets |
| `RateLimit-Limit` | Active per-minute or per-hour limit |
| `RateLimit-Remaining` | Remaining requests in the active window |
| `RateLimit-Reset` | Seconds until the active window resets |
| `Retry-After` | Seconds to wait before retrying; present on HTTP `429` rate-limit responses |

Monthly quota responses include quota-specific headers when available:

| Header | Description |
|--------|-------------|
| `X-Quota-Limit` | Monthly request or credit limit |
| `X-Quota-Used` | Amount used in the current billing cycle |
| `X-Quota-Remaining` | Amount remaining in the current billing cycle |
| `X-Quota-Reset` | Unix timestamp when the current billing cycle resets |

## Credit Usage

- **Events Search:** 3 credits per completed person events search request
> Credits are charged upon successful completion. If no event attendees are found, the request still consumes credits as the search was performed.
---

## POST /person/eventsQueue an event-based person search.
### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `event` | string | Yes | Public event, conference, podcast, etc. (e.g. "YC Demo Day", "TechCrunch Disrupt") |
| `company_name` | string | No | Filter by company to find employees who attended (e.g. "Google", "Stripe") |
| `role` | string | No | Filter by job title or role (e.g. "Founder", "CTO", "VP Engineering") |
| `industry` | string | No | Filter by industry sector (e.g. "Health Tech", "Fintech", "SaaS") |
| `location` | string | No | Geographic filter for attendees (e.g. "San Francisco", "New York") |
| `callback_url` | string | No | HTTPS endpoint for automatic delivery when results are ready |

> **Required:** The event field is required. All other fields are optional and serve as filters.
### Request Examples

**With Advanced Features:**

```json
{
  "event": "YC Demo Day",
  "role": "Founder",
  "industry": "Health Tech",
  "location": "San Francisco"
}
```

**Basic Request:**

```json
{
  "event": "TechCrunch Disrupt 2024"
}
```

### Code Examples

**cURL:**

```bash
curl -X POST https://api.nyne.ai/person/events \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "TechCrunch Disrupt 2024"
  }'
```

**Python:**

```python
import requests
import json

url = "https://api.nyne.ai/person/events"
headers = {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json"
}

data = {
    "event": "TechCrunch Disrupt 2024"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(json.dumps(result, indent=2))
```

**JavaScript:**

```javascript
const url = "https://api.nyne.ai/person/events";
const headers = {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json"
};

const data = {
    event: "TechCrunch Disrupt 2024"
};

fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(data)
})
.then(response => response.json())
.then(result => console.log(result))
.catch(error => console.error("Error:", error));
```

**PHP:**

```php
<?php
$url = "https://api.nyne.ai/person/events";
$headers = [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json"
];

$data = [
    "event" => "TechCrunch Disrupt 2024"
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$result = json_decode($response, true);
curl_close($ch);

echo json_encode($result, JSON_PRETTY_PRINT);
?>
```

### Response Codes

| Code | Description |
|------|-------------|
| 200 | Events search queued successfully |
| 400 | Invalid request parameters |
| 401 | Invalid API credentials |
| 429 | Rate limit exceeded |

### Response Example

```json
{
  "success": true,
  "data": {
    "request_id": "pevents_64f2d8e4_1700000789",
    "status": "queued",
    "message": "Person events request queued. Use GET /person/events?request_id=... to check status.",
    "callback_url": "https://example.com/webhooks/person-events"
  },
  "timestamp": "2025-11-10T22:44:03Z"
}
```

---

## GET /person/events
Check the status of a request.

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `request_id` | string | Yes | The request ID returned from the POST call |

### Request Example

```
GET /person/events?request_id=pevents_64f2d8e4_1700000789
```

### Response Codes

| Code | Description |
|------|-------------|
| 200 | Status retrieved successfully |
| 400 | Invalid request parameters |
| 401 | Invalid API credentials |
| 404 | Request ID not found |

### Response Example

```json
{
  "success": true,
  "data": {
    "request_id": "pevents_64f2d8e4_1700000789",
    "status": "completed",
    "result": {
      "people": [
        {
          "name": "Alex Doe",
          "title": "Co-founder",
          "company": "HealthPulse",
          "linkedin_url": "https://www.linkedin.com/in/alexdoe",
          "event": "YC Demo Day Summer 2025"
        }
      ]
    },
    "created_on": "2025-11-10T22:44:03Z",
    "completed_on": "2025-11-10T22:44:35Z"
  },
  "timestamp": "2025-11-10T22:44:35Z"
}
```

---

## Response Format

All API responses follow a consistent JSON format. All fields in enrichment results are **optional** and only included when data is available:
- Results are returned in the people array within result- Each person object includes name, title, company, linkedin_url, and event fields- If a field has no data, it will be omitted from the response- The people array may contain zero or more results depending on the event and filters
---

## Error Codes

| HTTP Code | Error Code | Description |
|-----------|------------|-------------|
| 400 | `missing_parameters` | The event field is required |
| 400 | `invalid_callback_url` | Callback URL must be HTTPS |
| 401 | `invalid_credentials` | API key or secret is incorrect |
| 403 | `subscription_required` | Account lacks search access |
| 429 | `rate_limit_exceeded` | Rate limit exceeded |
| 429 | `monthly_limit_exceeded` | Monthly usage limit exceeded |
| 402 | `insufficient_credits` | Account credits depleted |

---

## Callbacks

When you provide a `callback_url`, the API sends results to your endpoint via HTTP POST.

### Retry Policy- Maximum 5 retry attempts- Exponential backoff: 1s, 5s, 15s, 1m, 5m- 30-second timeout per request- Your endpoint should return HTTP 2xx for success
Your callback endpoint should respond with HTTP 200-299. Any other code triggers a retry.

### Callback Payload Example

```json
POST https://example.com/webhooks/person-events
Content-Type: application/json

{
  "request_id": "pevents_64f2d8e4_1700000789",
  "status": "completed",
  "result": {
    "people": [
      {
        "name": "Alex Doe",
        "title": "Co-founder",
        "company": "HealthPulse",
        "linkedin_url": "https://www.linkedin.com/in/alexdoe",
        "event": "YC Demo Day Summer 2025"
      }
    ]
  },
  "created_at": "2025-11-10T22:44:03Z",
  "completed_at": "2025-11-10T22:44:35Z"
}
```

---

## Best Practices

Prioritize inputs in this order for best match rates:
1. **Specific Event Names** (Best) — Use the full official event name with year (e.g. "TechCrunch Disrupt 2024") for the most accurate results.2. **Combine Filters** (Good) — Add role, industry, or location filters to narrow results to the most relevant attendees for your outreach.3. **Use Callbacks** (Good) — Provide a callback_url for production workflows instead of polling, to receive results as soon as they are ready.
---

## Note for AI Agents
When integrating with AI agents, submit the event search via POST and poll using the returned request_id. Parse the people array from the completed response to extract attendee names, titles, companies, and LinkedIn URLs for downstream enrichment or outreach workflows.
---

## Related APIs
- **Person Search API** — Search for contacts by company and role → `https://api.nyne.ai/documentation/person/search`
- **Person Enrichment API** — Enrich event attendee profiles → `https://api.nyne.ai/documentation/person/enrichment`
- **Company Search API** — Search for companies by criteria → `https://api.nyne.ai/documentation/company/search`