# Single Social Lookup API
> Look up a specific social media profile URL for a person using their email address or another social media URL
**Base URL:** `https://api.nyne.ai`
**Endpoint:** `https://api.nyne.ai/person/single-social-lookup`

---

## Overview
The Single Social Lookup API allows you to find a person's profile URL on a specific social media platform, given their email address or a profile URL from another platform. This is useful when you have a person's profile on one platform and want to find their profile on another, or when you have their email and want to find a specific social account. Delivery is asynchronous: submit a request, receive a request_id, then poll or register a callback.
### What You Get
- **Targeted Lookup:** Specify exactly which social platform you want to find- **Flexible Input:** Use either an email address or a social media URL as input- **Cross-Platform Discovery:** Map from one social platform to another- **Simple Response:** Returns just the URL you're looking for- **Credit-Based:** Charges only when a matching profile is found
## 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

- **Single Social Lookup:**  credits per successful request
> Credits are only charged when a matching profile URL is found. If no profile is found for the requested site, no credits are charged.
---

## POST /person/single-social-lookupLook up a specific social media profile URL for a person.
### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `social_media_url` | string | No | A social media profile URL to look up from |
| `email` | string | No | Email address to look up from |
| `site` | string | Yes | The target social media site name to find the profile for (e.g. twitter, linkedin, instagram, facebook, tiktok, pinterest, github) |
| `callback_url` | string | No | URL to receive results asynchronously |

> **Required:** Either social_media_url or email must be provided, plus the site parameter.
### Request Examples

**With Advanced Features:**

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

**Basic Request:**

```json
{
  "social_media_url": "https://linkedin.com/in/johndoe",
  "site": "twitter"
}
```

### Code Examples

**cURL:**

```bash
curl -X POST https://api.nyne.ai/person/single-social-lookup \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "social_media_url": "https://linkedin.com/in/johndoe",
    "site": "twitter"
  }'
```

**Python:**

```python
import requests
import json

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

data = {
    "social_media_url": "https://linkedin.com/in/johndoe",
    "site": "twitter"
}

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

const data = {
    social_media_url: "https://linkedin.com/in/johndoe",
    site: "twitter"
};

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

$data = [
    "social_media_url" => "https://linkedin.com/in/johndoe",
    "site" => "twitter"
];

$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": "Single social lookup request queued. Use GET /person/single-social-lookup?request_id=... to check status."
  },
  "timestamp": "2025-01-15T10:30:00Z"
}
```

---

## GET /person/single-social-lookup
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/single-social-lookup?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",
    "target_site": "twitter",
    "result": {
      "url": "https://twitter.com/johndoe",
      "found": true
    }
  },
  "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 returns a response with the result nested in a result object- target_site contains the site name you requested- result.url is the profile URL if found, or null if not found- result.found is a boolean indicating whether a profile was found- Credits are only charged when result.found is true
---

## Error Codes

| HTTP Code | Error Code | Description |
|-----------|------------|-------------|
| 400 | `missing_parameters` | Either social_media_url or email is required, plus site parameter |
| 400 | `invalid_email` | Invalid email format |
| 400 | `invalid_url` | Invalid social media URL format |
| 400 | `unrecognized_site` | Could not recognize the site from the provided URL or site name |
| 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. Wait and retry. |
| 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",
  "target_site": "twitter",
  "result": {
    "url": "https://twitter.com/johndoe",
    "found": true
  },
  "timestamp": "2025-01-15T10:30:05Z"
}
```

---

## Related APIs
- **Social Profiles API** — Find all social accounts at once → `https://api.nyne.ai/documentation/person/social-profiles`
- **Person Enrichment API** — Full person profile lookup → `https://api.nyne.ai/documentation/person/enrichment`