> ## 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 Enrichment API

> Enrich person profiles using GitHub username, LinkedIn username, or email address

## Endpoint

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

This endpoint enriches a person's profile by searching GitHub and LinkedIn data using either a GitHub username, LinkedIn username, or email address.

***

## Authentication

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

See the [Authentication Guide](/guides/authentication) for detailed setup instructions.

***

## Request Parameters

### Request Body (JSON)

At least one identifier is required:

<ParamField body="github" type="string">
  GitHub username to search for.

  **Example:** `"torvalds"`
</ParamField>

<ParamField body="linkedin_username" type="string">
  LinkedIn username to search for.

  **Example:** `"williamhgates"`

  <Note>This is the LinkedIn profile slug (e.g., from linkedin.com/in/**williamhgates**).</Note>
</ParamField>

<ParamField body="email" type="string">
  Email address to search for in GitHub and LinkedIn profiles.

  **Example:** `"user@example.com"`

  <Note>The API searches the `emails` array in our data for matches across all requested websets.</Note>
</ParamField>

<ParamField body="websets" type="string[]" default="[&#x22;github&#x22;]">
  List of data sources to include in the enrichment.

  **Available websets:**

  * `github` - GitHub profile data (repos, commits, activity)
  * `linkedin` - LinkedIn profile data (experience, education, certifications)

  **Example:** `["github", "linkedin"]`
</ParamField>

<Note>
  **Identifier Priority**: The API will try to find profiles by specific identifiers first (github, linkedin\_username), then fall back to email search if not found.
</Note>

***

## Response

### Success Response (200 OK)

Returns a JSON object containing the enriched profile data.

<ResponseField name="websets_matched" type="string[]">
  Array of websets that successfully matched and returned data. For example: `["github"]`
</ResponseField>

<ResponseField name="person" type="object">
  Container object for all enriched profile data

  <ResponseField name="github" type="object">
    GitHub profile data (when `"github"` webset is requested and a match is found)

    <ResponseField name="user_id" type="integer">
      GitHub user ID
    </ResponseField>

    <ResponseField name="github_username" type="string">
      GitHub username
    </ResponseField>

    <ResponseField name="full_name" type="string">
      User's full name
    </ResponseField>

    <ResponseField name="bio" type="string">
      GitHub bio/description
    </ResponseField>

    <ResponseField name="github" type="object">
      Nested object containing detailed GitHub account information including avatar\_url, company, location, followers, following, public\_repos, public\_gists, type, created\_at, and updated\_at
    </ResponseField>

    <ResponseField name="names" type="array">
      Array of names found across different sources
    </ResponseField>

    <ResponseField name="emails" type="array">
      Array of email addresses associated with the profile
    </ResponseField>

    <ResponseField name="email" type="string">
      Primary email address
    </ResponseField>

    <ResponseField name="social_accounts" type="array">
      Array of social media account URLs
    </ResponseField>

    <ResponseField name="linkedin_username" type="string">
      LinkedIn username
    </ResponseField>

    <ResponseField name="location" type="string">
      Location string from GitHub profile
    </ResponseField>

    <ResponseField name="location_canonical" type="object">
      Structured location data with city, state, country, country\_code, latitude, longitude, postal\_code, continent, label, and timezone
    </ResponseField>

    <ResponseField name="repos" type="array">
      Array of repository objects with metadata (repo\_id, full\_name, name, description, language, stargazers\_count, forks\_count, created\_at, updated\_at, etc.)
    </ResponseField>

    <ResponseField name="commits" type="array">
      Array of commit objects with sha, author\_name, author\_email, message, and related repository information
    </ResponseField>

    <Note>Additional fields may be present depending on the data available in the GitHub profile.</Note>
  </ResponseField>
</ResponseField>

### No Match Response (200 OK)

When no matching profile is found:

```json theme={null}
{
  "person": {},
  "websets_matched": []
}
```

### Error Responses

All error responses follow the standard format with a `detail` field:

```json theme={null}
{
  "detail": "Error message describing what went wrong"
}
```

**Error Status Codes:**

* **401 Unauthorized** - Missing or invalid API key
* **403 Forbidden** - Organization is inactive
* **422 Unprocessable Entity** - Validation error (missing required parameters or invalid values)
* **429 Too Many Requests** - Monthly request limit exceeded
* **500 Internal Server Error** - Unexpected server error (e.g., Elasticsearch connection failed)

***

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  # Enrich by GitHub username
  curl -X POST "https://api.peoplecontext.com/v1/person/enrich" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"github": "torvalds", "websets": ["github"]}'

  # Enrich by LinkedIn username
  curl -X POST "https://api.peoplecontext.com/v1/person/enrich" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"linkedin_username": "williamhgates", "websets": ["linkedin"]}'

  # Enrich with both GitHub and LinkedIn
  curl -X POST "https://api.peoplecontext.com/v1/person/enrich" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"github": "torvalds", "linkedin_username": "linustorvalds", "websets": ["github", "linkedin"]}'

  # Enrich by email
  curl -X POST "https://api.peoplecontext.com/v1/person/enrich" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"email": "user@example.com", "websets": ["github", "linkedin"]}'
  ```

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

  url = "https://api.peoplecontext.com/v1/person/enrich"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
  }

  # Enrich by GitHub username
  payload = {
      "github": "torvalds",
      "websets": ["github"]
  }

  response = requests.post(url, headers=headers, json=payload)
  data = response.json()

  person = data.get("person", {})
  github = person.get("github", {})

  if github:
      print(f"Name: {github.get('full_name')}")
      print(f"Emails: {github.get('emails')}")
      print(f"Repos: {github.get('public_repos')}")
  else:
      print("No match found")

  # Enrich with both GitHub and LinkedIn
  payload = {
      "github": "torvalds",
      "linkedin_username": "linustorvalds",
      "websets": ["github", "linkedin"]
  }

  response = requests.post(url, headers=headers, json=payload)
  data = response.json()

  if "github" in data["person"]:
      print(f"GitHub: {data['person']['github']['github_username']}")
  if "linkedin" in data["person"]:
      print(f"LinkedIn: {data['person']['linkedin']['linkedin_username']}")
  ```

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

  const data = await response.json();
  const github = data.person?.github;

  if (github) {
    console.log(`Name: ${github.full_name}`);
    console.log(`Emails: ${github.emails}`);
    console.log(`Repos: ${github.public_repos}`);
  } else {
    console.log('No match found');
  }
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init();

  $payload = json_encode([
      'github' => 'torvalds',
      'websets' => ['github']
  ]);

  curl_setopt($ch, CURLOPT_URL, "https://api.peoplecontext.com/v1/person/enrich");
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'Authorization: Bearer YOUR_API_KEY',
      'Content-Type: application/json'
  ]);

  $response = curl_exec($ch);
  curl_close($ch);

  $data = json_decode($response, true);
  $github = $data['person']['github'] ?? null;

  if ($github) {
      echo "Name: " . $github['full_name'] . "\n";
      echo "Emails: " . implode(', ', $github['emails']) . "\n";
  }
  ?>
  ```
</CodeGroup>

***

## Sample Response

```json theme={null}
{
  "websets_matched": ["github"],
  "person": {
    "github": {
      "user_id": 1024025,
      "github_username": "torvalds",
      "full_name": "Linus Torvalds",
      "bio": "Creator of Linux and Git",
      "github": {
        "user_id": 1024025,
        "github_username": "torvalds",
        "avatar_url": "https://avatars.githubusercontent.com/u/1024025?",
        "company": "@linuxfoundation",
        "location": "Portland, OR",
        "followers": 180000,
        "following": 0,
        "public_repos": 6,
        "public_gists": 0,
        "type": "user",
        "created_at": "2011-09-03",
        "updated_at": "2025-12-01"
      },
      "names": ["Linus Torvalds", "torvalds"],
      "emails": ["torvalds@linux-foundation.org"],
      "email": "torvalds@linux-foundation.org",
      "social_accounts": ["twitter.com/linus__torvalds"],
      "linkedin_username": "linustorvalds",
      "location": "Portland, OR",
      "location_canonical": {
        "city": "Portland",
        "state": "Oregon",
        "country": "United States",
        "country_code": "USA",
        "latitude": 45.523064,
        "longitude": -122.676483,
        "postal_code": "97035",
        "continent": "North America",
        "label": "Portland, OR, USA",
        "timezone": "America/Los_Angeles"
      },
      "repos": [
        {
          "repo_id": 2325298,
          "full_name": "torvalds/linux",
          "name": "linux",
          "description": "Linux kernel source tree",
          "language": "C",
          "stargazers_count": 150000,
          "forks_count": 48000,
          "created_at": "2011-09-04",
          "updated_at": "2025-12-01",
          "owner": {}
        }
      ],
      "commits": [
        {
          "sha": "1da177e4c3f41524e886b7f1b8a0c1fc7321cac2",
          "author_name": "Linus Torvalds",
          "author_email": "torvalds@linux-foundation.org",
          "message": "Linux-2.6.12-rc2"
        }
      ]
    }
  }
}
```

***

## Best Practices

<Tip>
  **Email Search for Lead Enrichment**: If you have email addresses but not GitHub usernames, you can still find profiles by searching with the email parameter. The API searches the emails array in our GitHub data.
</Tip>

<Warning>
  **Rate Limits**: API requests are subject to rate limits based on your organization's plan. Monitor your monthly request count to avoid hitting limits.
</Warning>

<Note>
  **Data Freshness**: GitHub data is refreshed monthly. Check the profile data for recent activity and timestamps.
</Note>

***

## Related

* [GitHub Webset Guide](/guides/github-webset) - Overview, use cases, and features
* [Quickstart](/quickstart) - Get started in 5 minutes
* [Introduction](/introduction) - Learn about People Context API