> ## 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.

# Context API

> Send unstructured person data and get back enriched, structured profiles with custom fields

<Warning>
  **Experimental Feature**: The Context API is currently in active development and may undergo changes. Contact [justin@peoplecontext.com](mailto:justin@peoplecontext.com) for early access.
</Warning>

## Overview

The Context API is our most powerful endpoint. Send us unstructured data about a person, and we'll:

1. **Enrich** the profile with data from our websets
2. **Structure** the data into our standard schema
3. **Generate** custom fields using LLMs based on your requirements

## Endpoint

```
POST /v1/context
```

## Request Parameters

<ParamField body="person" type="string | object" required>
  Unstructured data about a person. Can be a string or an object with any fields.

  **Examples:**

  * String: `"Justin Connell works at PeopleContext — his email is justin@peoplecontext.com"`
  * Object: `{"name": "Justin", "company": "PeopleContext", "linkedin": "https://linkedin.com/in/justinconnell"}`
</ParamField>

<ParamField body="schema" type="object">
  Custom fields you want generated for this profile. Each field should have a `type` and `description`.

  **Example:**

  ```json theme={null}
  {
    "fit_score": {
      "type": "number",
      "description": "How well this person matches the job: Senior Python Engineer, SF-based"
    },
    "email_copy": {
      "type": "string",
      "description": "A personalized email inviting them to apply"
    }
  }
  ```
</ParamField>

<ParamField body="confidence" type="number" default="0.9">
  Minimum confidence threshold for returned data (0.0 - 1.0). Higher values return more accurate data but may exclude some information.
</ParamField>

<ParamField body="webhook_url" type="string">
  Optional webhook URL to receive the enriched profile asynchronously.
</ParamField>

<ParamField body="response_timeout_sec" type="number" default="30">
  Maximum time to wait for enrichment before sending to webhook.
</ParamField>

## Response Schema

The response includes:

* All standard profile fields (from our unified schema)
* A `custom` object with your requested custom fields
* Confidence scores for generated fields

```json theme={null}
{
  "first_name": "Justin",
  "last_name": "Connell",
  "full_name": "Justin Connell",
  "personal_email": "justin@peoplecontext.com",
  "github": {
    "url": "https://github.com/justinconnell",
    "username": "justinconnell",
    "id": 123456
  },
  "linkedin": {
    "url": "https://www.linkedin.com/in/justinconnell",
    "username": "justinconnell",
    "headline": "Founder at PeopleContext"
  },
  "current_position": {
    "summary": "Founder & CEO",
    "start": "2025-02-01",
    "company": {
      "name": "PeopleContext",
      "linkedin_url": "https://www.linkedin.com/company/peoplecontextai"
    }
  },
  "custom": {
    "fit_score": 0.85,
    "email_copy": "Hi Justin,\n\nI came across your profile and was impressed by your work at PeopleContext..."
  }
}
```

## Code Examples

### Basic Enrichment

<CodeGroup>
  ```python Python theme={null}
  import requests

  API_KEY = "your_api_key_here"
  BASE_URL = "https://api.peoplecontext.com"

  headers = {
      "Authorization": f"Bearer {API_KEY}",
      "Content-Type": "application/json"
  }

  # Simple string input
  payload = {
      "person": "Justin Connell works at PeopleContext — his email is justin@peoplecontext.com"
  }

  response = requests.post(
      f"{BASE_URL}/v1/context",
      headers=headers,
      json=payload
  )

  profile = response.json()
  print(f"Name: {profile['full_name']}")
  print(f"Email: {profile['personal_email']}")
  ```

  ```javascript Node.js theme={null}
  const axios = require('axios');

  const API_KEY = 'your_api_key_here';
  const BASE_URL = 'https://api.peoplecontext.com';

  const headers = {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  };

  // Simple string input
  const payload = {
    person: 'Justin Connell works at PeopleContext — his email is justin@peoplecontext.com'
  };

  const response = await axios.post(
    `${BASE_URL}/v1/context`,
    payload,
    { headers }
  );

  const profile = response.data;
  console.log(`Name: ${profile.full_name}`);
  console.log(`Email: ${profile.personal_email}`);
  ```
</CodeGroup>

### With Custom Schema

<CodeGroup>
  ```python Python theme={null}
  # Enrich with custom fields
  payload = {
      "person": {
          "name": "Justin Connell",
          "company": "PeopleContext",
          "linkedin": "https://linkedin.com/in/justinconnell"
      },
      "schema": {
          "fit_score": {
              "type": "number",
              "description": "How well this person matches: Senior Python Engineer, 5+ years, SF Bay Area. Score 0.0-1.0"
          },
          "email_copy": {
              "type": "string",
              "description": "A personalized 2-3 sentence email inviting them to apply for the Senior Python Engineer role"
          },
          "key_strengths": {
              "type": "array",
              "description": "List of 3-5 key technical strengths based on their experience"
          }
      },
      "confidence": 0.9
  }

  response = requests.post(
      f"{BASE_URL}/v1/context",
      headers=headers,
      json=payload
  )

  profile = response.json()

  # Access custom fields
  print(f"Fit Score: {profile['custom']['fit_score']}")
  print(f"Email:\n{profile['custom']['email_copy']}")
  print(f"Strengths: {', '.join(profile['custom']['key_strengths'])}")
  ```

  ```javascript Node.js theme={null}
  // Enrich with custom fields
  const payload = {
    person: {
      name: 'Justin Connell',
      company: 'PeopleContext',
      linkedin: 'https://linkedin.com/in/justinconnell'
    },
    schema: {
      fit_score: {
        type: 'number',
        description: 'How well this person matches: Senior Python Engineer, 5+ years, SF Bay Area. Score 0.0-1.0'
      },
      email_copy: {
        type: 'string',
        description: 'A personalized 2-3 sentence email inviting them to apply'
      },
      key_strengths: {
        type: 'array',
        description: 'List of 3-5 key technical strengths based on their experience'
      }
    },
    confidence: 0.9
  };

  const response = await axios.post(
    `${BASE_URL}/v1/context`,
    payload,
    { headers }
  );

  const profile = response.data;

  // Access custom fields
  console.log(`Fit Score: ${profile.custom.fit_score}`);
  console.log(`Email:\n${profile.custom.email_copy}`);
  console.log(`Strengths: ${profile.custom.key_strengths.join(', ')}`);
  ```
</CodeGroup>

### Async with Webhooks

```python Python theme={null}
# For long-running enrichment, use webhooks
payload = {
    "person": "Justin Connell, CEO at PeopleContext",
    "schema": {
        "fit_score": {
            "type": "number",
            "description": "Fit for executive role"
        }
    },
    "webhook_url": "https://yourapp.com/webhooks/context",
    "response_timeout_sec": 10
}

# Request returns immediately if processing takes longer than 10 seconds
response = requests.post(
    f"{BASE_URL}/v1/context",
    headers=headers,
    json=payload
)

# Result will be POSTed to your webhook URL when ready
```

## Use Cases

### Recruiting - Candidate Scoring

Score candidates automatically based on job requirements:

```python theme={null}
job_description = """
Senior Python Engineer
Requirements:
- 5+ years Python experience
- Experience with FastAPI, Django, or Flask
- Cloud deployment (AWS/GCP)
- SF Bay Area based or remote
"""

def score_candidate(person_data):
    payload = {
        "person": person_data,
        "schema": {
            "fit_score": {
                "type": "number",
                "description": f"How well this person matches this role (0.0-1.0):\n{job_description}"
            },
            "match_reasons": {
                "type": "array",
                "description": "3-5 specific reasons why they match or don't match"
            },
            "red_flags": {
                "type": "array",
                "description": "Any concerns or missing qualifications"
            }
        }
    }

    response = requests.post(
        f"{BASE_URL}/v1/context",
        headers=headers,
        json=payload
    )

    return response.json()

# Use it
candidate = score_candidate("Jane Smith, Senior Backend Engineer at Stripe")
print(f"Fit: {candidate['custom']['fit_score']}")
print(f"Reasons: {candidate['custom']['match_reasons']}")
```

### Sales - Lead Qualification

Qualify and score leads automatically:

```python theme={null}
def qualify_lead(person_info, company_criteria):
    payload = {
        "person": person_info,
        "schema": {
            "is_decision_maker": {
                "type": "boolean",
                "description": "Is this person a decision-maker for enterprise software purchases?"
            },
            "company_size_match": {
                "type": "boolean",
                "description": f"Does their company match our ICP: {company_criteria}"
            },
            "outreach_angle": {
                "type": "string",
                "description": "Best angle for outreach based on their background and current role"
            },
            "priority_score": {
                "type": "number",
                "description": "Priority score 1-10 based on fit and likelihood to convert"
            }
        }
    }

    response = requests.post(
        f"{BASE_URL}/v1/context",
        headers=headers,
        json=payload
    )

    return response.json()
```

### Content Personalization

Generate personalized content at scale:

```python theme={null}
def generate_personalized_email(recipient_info, campaign_goal):
    payload = {
        "person": recipient_info,
        "schema": {
            "subject_line": {
                "type": "string",
                "description": "Personalized email subject line that references their background"
            },
            "email_body": {
                "type": "string",
                "description": f"3-paragraph personalized email with goal: {campaign_goal}"
            },
            "call_to_action": {
                "type": "string",
                "description": "Specific CTA based on their seniority and role"
            }
        }
    }

    response = requests.post(
        f"{BASE_URL}/v1/context",
        headers=headers,
        json=payload
    )

    return response.json()

# Use it
email = generate_personalized_email(
    "Sarah Chen, VP Engineering at Airbnb",
    "Invite to our AI Engineering Summit"
)

print(f"Subject: {email['custom']['subject_line']}")
print(f"Body:\n{email['custom']['email_body']}")
```

## Best Practices

<AccordionGroup>
  <Accordion icon="message" title="Write Clear Schema Descriptions">
    The quality of custom fields depends on clear, detailed descriptions:

    **Good:**

    ```json theme={null}
    {
      "fit_score": {
        "type": "number",
        "description": "How well this person matches: Senior Python Engineer, 5+ years experience, SF-based, startup experience preferred. Score 0.0-1.0 where 1.0 is perfect match."
      }
    }
    ```

    **Bad:**

    ```json theme={null}
    {
      "fit_score": {
        "type": "number",
        "description": "Score the person"
      }
    }
    ```
  </Accordion>

  <Accordion icon="gauge" title="Adjust Confidence Levels">
    Use different confidence levels based on your use case:

    * **High confidence (0.95+)**: Critical decisions, compliance
    * **Medium confidence (0.85-0.95)**: General enrichment, CRM data
    * **Lower confidence (0.75-0.85)**: Exploratory analysis, lead generation
  </Accordion>

  <Accordion icon="webhook" title="Use Webhooks for Batch Processing">
    For processing large volumes, use webhooks to avoid timeouts:

    ```python theme={null}
    # Process 1000 leads
    for lead in leads:
        requests.post(
            f"{BASE_URL}/v1/context",
            headers=headers,
            json={
                "person": lead,
                "schema": scoring_schema,
                "webhook_url": "https://yourapp.com/webhooks/lead-scored",
                "response_timeout_sec": 5
            }
        )

    # Results arrive at your webhook as they complete
    ```
  </Accordion>
</AccordionGroup>

## Pricing

Context API pricing is based on:

* **Base enrichment**: Standard per-request fee
* **Custom field generation**: Additional cost per custom field
* **Data sources accessed**: May incur additional costs for premium data

Contact sales for detailed pricing.

## FAQ

<AccordionGroup>
  <Accordion title="When will the Context API be available?">
    The Context API is currently in development. Contact [justin@peoplecontext.com](mailto:justin@peoplecontext.com) to express interest and be notified when it launches.
  </Accordion>

  <Accordion title="What LLM powers custom field generation?">
    We use state-of-the-art LLMs (GPT-4, Claude, etc.) optimized for accuracy and cost-efficiency.
  </Accordion>

  <Accordion title="Can I use my own LLM for custom fields?">
    Enterprise customers can integrate their own LLM endpoints. Contact sales for details.
  </Accordion>

  <Accordion title="How accurate are generated custom fields?">
    Accuracy depends on:

    * Input data quality
    * Schema description clarity
    * Confidence threshold
    * Complexity of the field

    We recommend testing with your specific use case and adjusting the confidence threshold accordingly.
  </Accordion>
</AccordionGroup>