> ## Documentation Index
> Fetch the complete documentation index at: https://docs.peoplecontext.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Person Discovery API

> Discover related social media profiles from a LinkedIn, GitHub, or Twitter/X username

## Endpoint

```http theme={null}
POST /v1/person/discover
```

Given a username or profile URL for any supported platform, this endpoint discovers the same person's profiles on the other platforms using index lookups, search, and entity matching.

***

## Authentication

<ParamField header="Authorization" type="string" required>
  Bearer token with your API key: `Bearer YOUR_API_KEY`
</ParamField>

***

## Request Parameters

### Request Body (JSON)

Provide **exactly one** of the following fields:

<ParamField body="linkedin" type="string">
  LinkedIn username or profile URL.

  **Examples:** `"williamhgates"`, `"https://www.linkedin.com/in/williamhgates"`
</ParamField>

<ParamField body="github" type="string">
  GitHub username or profile URL.

  **Examples:** `"torvalds"`, `"https://github.com/torvalds"`
</ParamField>

<ParamField body="twitter" type="string">
  Twitter/X username or profile URL.

  **Examples:** `"elonmusk"`, `"https://x.com/elonmusk"`
</ParamField>

<ParamField body="url" type="string">
  A profile URL from any supported platform. The platform is auto-detected from the URL.

  **Examples:** `"https://github.com/torvalds"`, `"https://linkedin.com/in/williamhgates"`, `"https://x.com/elonmusk"`
</ParamField>

<Warning>
  You must provide exactly one identifier. Sending zero or more than one will return a 400 error.
</Warning>

***

## Response

### Success Response (200 OK)

<ResponseField name="socials" type="array">
  Array of discovered social profiles. The input profile is always included first with a confidence of 1.0.

  <ResponseField name="platform" type="string">
    Platform identifier: `"github"`, `"linkedin"`, or `"twitter"`.
  </ResponseField>

  <ResponseField name="username" type="string">
    Username on the platform (without URL prefix).
  </ResponseField>

  <ResponseField name="link" type="string">
    Full profile URL.
  </ResponseField>

  <ResponseField name="confidence" type="number">
    Confidence score from 0.0 to 1.0 that the profile belongs to the same person. The input profile always has confidence 1.0. Only discovered profiles scoring >= 0.45 are returned.
  </ResponseField>

  <ResponseField name="context" type="string | null">
    Rich text summary of the profile, including bio, headline, experience, skills, and other relevant data. Useful for downstream enrichment or display. May be `null` if profile data is unavailable.
  </ResponseField>
</ResponseField>

### Error Responses

* **400 Bad Request** - Must provide exactly one identifier (`linkedin`, `github`, `twitter`, or `url`)
* **401 Unauthorized** - Missing or invalid API key
* **429 Too Many Requests** - Rate limit or quota exceeded

***

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.peoplecontext.com/v1/person/discover" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"github": "torvalds"}'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.peoplecontext.com/v1/person/discover",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      json={"github": "torvalds"}
  )

  for social in response.json().get("socials", []):
      print(f"{social['platform']}: {social['username']} (confidence: {social['confidence']})")
      if social.get("context"):
          print(f"  Context: {social['context'][:100]}...")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.peoplecontext.com/v1/person/discover',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ github: 'torvalds' })
    }
  );

  const data = await response.json();
  data.socials?.forEach(s =>
    console.log(`${s.platform}: ${s.username} (${s.confidence})`)
  );
  ```
</CodeGroup>

***

## Sample Response

```json theme={null}
{
  "socials": [
    {
      "platform": "github",
      "username": "torvalds",
      "link": "https://github.com/torvalds",
      "confidence": 1.0,
      "context": "name: Linus Torvalds\n- username: torvalds\n- url: github.com/torvalds\n- company: Linux Foundation\n- location: Portland, OR\n..."
    },
    {
      "platform": "linkedin",
      "username": "linustorvalds",
      "link": "https://linkedin.com/in/linustorvalds",
      "confidence": 0.95,
      "context": "name: Linus Torvalds\n- headline: Fellow at Linux Foundation\n..."
    },
    {
      "platform": "twitter",
      "username": "Linus__Torvalds",
      "link": "https://x.com/Linus__Torvalds",
      "confidence": 0.87,
      "context": "name: Linus Torvalds\n- username: @Linus__Torvalds\n- bio: Creator of Linux and Git\n..."
    }
  ]
}
```