# Social Profiles API
> Look up social media profiles for individuals using email addresses, phone numbers, or social media URLs
**Base URL:** `https://api.nyne.ai`
**Endpoint:** `https://api.nyne.ai/person/social-profiles`

---

## Overview
Find all of someone's social media accounts using just their email address or one social profile URL. If you have one of their profiles, this API can find their accounts across other platforms.

**Input:** Provide an email address, phone number, or any social media profile URL

**Output:** A list of all social media profiles associated with that person
### What You Get
- **Professional network profiles:** LinkedIn and other career-focused platforms- **Microblogging and social profiles:** Twitter/X, Mastodon, and similar platforms- **Photo and video sharing profiles:** Instagram, Flickr, and image-sharing services- **Video platform channels:** YouTube and other video hosting platforms- **Developer platform profiles:** GitHub, GitLab, Stack Overflow, and coding communities- **Publishing and newsletter profiles:** Substack, Medium, and content publishing platforms
## 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

- **Social Profiles Lookup:** 5 credits per successful request (at least one social profile URL found)
> Credits are only charged when at least one social profile URL is found. If no profiles are discovered, no credits are charged.
---

## POST /person/social-profilesLook up social media profiles for a person using email, phone, or social media URL.
### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `email` | string | No | Email address to look up |
| `phone` | string | No | Phone number to look up |
| `social_media_url` | string | No | Social media profile URL (LinkedIn, Twitter, etc.) |
| `callback_url` | string | No | URL to receive results asynchronously |

> **Required:** At least one of email, phone, or social_media_url must be provided.
### Request Examples

**With Advanced Features:**

```json
{
  "email": "john.doe@example.com",
  "callback_url": "https://yourapp.com/webhook/social-profiles"
}
```

**Basic Request:**

```json
{
  "email": "john.doe@example.com"
}
```

### Code Examples

**cURL:**

```bash
curl -X POST https://api.nyne.ai/person/social-profiles \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.doe@example.com"
  }'
```

**Python:**

```python
import requests
import json

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

data = {
    "email": "john.doe@example.com"
}

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/social-profiles";
const headers = {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json"
};

const data = {
    email: "john.doe@example.com"
};

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/social-profiles";
$headers = [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json"
];

$data = [
    "email" => "john.doe@example.com"
];

$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 |
|------|-------------|
| 202 | Request queued successfully |
| 400 | Invalid request parameters |
| 401 | Invalid API credentials |
| 402 | Insufficient credits |
| 429 | Rate limit exceeded |

### Response Example

```json
{
  "success": true,
  "data": {
    "request_id": "abc123def456...",
    "status": "queued",
    "message": "Social profiles lookup request queued. Use GET /person/social-profiles?request_id=... to check status."
  },
  "timestamp": "2025-01-15T10:30:00Z"
}
```

---

## GET /person/social-profiles
Check the status of a request.

### Parameters

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

### Request Example

```
GET /person/social-profiles?request_id=abc123def456...
```

### 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": "abc123def456...",
    "status": "completed",
    "social_profiles": {
      "twitter": {
        "url": "https://twitter.com/johndoe"
      },
      "linkedin": {
        "url": "https://www.linkedin.com/in/johndoe"
      },
      "youtube": {
        "url": "https://youtube.com/@johndoe"
      }
    }
  },
  "timestamp": "2025-01-15T10:30:05Z"
}
```

---

## Response Format

All API responses follow a consistent JSON format. All fields in enrichment results are **optional** and only included when data is available:
- The API searches for profiles across all supported social platforms. Only profiles that are found will be included in the response- Each platform key will only appear in the response if a matching profile was found- Each platform object contains a url field with the profile URL- If no profiles are found, the social_profiles object will be empty- Credits are only charged when at least one social profile URL is found
---

## Error Codes

| HTTP Code | Error Code | Description |
|-----------|------------|-------------|
| 400 | `missing_parameters` | At least one of email, phone, or social_media_url is required |
| 400 | `invalid_email` | Invalid email format |
| 400 | `invalid_phone` | Invalid phone number format |
| 400 | `invalid_url` | Invalid social media URL format |
| 401 | `invalid_credentials` | API key or secret is incorrect |
| 402 | `insufficient_credits` | Not enough credits available |
| 404 | `request_not_found` | Request ID not found (for status checks) |
| 429 | `rate_limit_exceeded` | Rate limit exceeded |
| 500 | `internal_error` | Internal server error |

---

## 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
{
  "request_id": "abc123def456...",
  "status": "completed",
  "success": true,
  "completed": true,
  "data": {
    "social_profiles": {
      "twitter": {
        "url": "https://twitter.com/johndoe"
      },
      "linkedin": {
        "url": "https://www.linkedin.com/in/johndoe"
      },
      "youtube": {
        "url": "https://youtube.com/@johndoe"
      }
    }
  },
  "completed_on": "2025-01-15T10:30:05Z",
  "timestamp": "2025-01-15T10:30:05Z"
}
```

---

## Best Practices

Prioritize inputs in this order for best match rates:
1. **Email Address** (Best) — Provides the broadest social graph discovery. Work emails may yield more professional profiles while personal emails often surface more social accounts.2. **Social Media URL** (Good) — If you already have one social profile, the API can discover accounts on other platforms linked to the same person.3. **Phone Number** (Lowest) — Generally has the lowest match rate. Use only when email or social media URL is unavailable.
---

## Note for AI Agents
Social profiles lookups are asynchronous. AI agents and automated systems should poll the GET endpoint with the returned request_id until the status is completed. Use exponential backoff when polling to avoid rate limits.
---

## Related APIs
- **Social Newsfeed API** — Get posts from discovered profiles → `https://api.nyne.ai/documentation/person/newsfeed`
- **Single Social Lookup API** — Find one specific platform profile → `https://api.nyne.ai/documentation/person/single-social-lookup`
- **Person Enrichment API** — Full person profile lookup → `https://api.nyne.ai/documentation/person/enrichment`