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

# Enrich Person

> Enrich a person from combined identity clues and receive an identity match score.

<Badge color="blue">20 Credits</Badge> <Badge color="green">All Paid Plans</Badge> <Badge color="purple">Beta Feature</Badge>


## OpenAPI

````yaml POST /people/enrich
openapi: 3.1.0
info:
  title: Context API
  description: API for retrieving context data from any website
  version: 1.0.0
servers:
  - url: https://api.context.dev/v1
security: []
tags:
  - name: Batch
    description: Scrape many pages or crawl a site asynchronously.
  - name: Monitors
    description: >-
      Monitor pages, sitemaps, and extracted website data for exact or semantic
      changes. Webhook payloads are documented by the
      MonitorsChangeDetectedWebhookPayload and
      MonitorsRunCompletedWebhookPayload schemas.
  - name: WebDBs
    description: Create structured tables from web pages and keep them up to date.
  - name: News
    description: >-
      Search live first-party RSS and free historical news data by company
      identity.
paths:
  /people/enrich:
    post:
      tags:
        - People
      summary: Enrich Person
      description: >-
        Finds and normalizes the best available person candidate from additive
        identity clues, then assigns an identity match score from 0 to 100.
        Available on all paid plans. Successful requests cost 20 credits.
        Disposable and free email addresses (like gmail.com, yahoo.com) will
        throw a 422 error.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonEnrichmentRequest'
            example:
              social_urls:
                - https://www.linkedin.com/in/ada-lovelace/
              name:
                first: Ada
                last: Lovelace
              company:
                name: Analytical Engines
                domain: analyticalengines.example
      responses:
        '200':
          description: >-
            The highest-scoring candidate, including weak matches, or a
            not-found result when no usable candidate exists.
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonEnrichmentResponse'
        '400':
          description: Bad request - Insufficient or invalid identity clues
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Invalid or missing API key
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - Insufficient permissions or usage limit exceeded
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '408':
          description: Request timeout
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity - Free email or disposable email detected
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
                  status:
                    type: string
                    description: Status of the response, e.g., 'error'
                  error_code:
                    type: string
                    enum:
                      - FREE_EMAIL_DETECTED
                      - DISPOSABLE_EMAIL_DETECTED
                    description: >-
                      Error code indicating whether a free email provider or
                      disposable email was detected
                  key_metadata:
                    $ref: '#/components/schemas/KeyMetadata'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          description: Internal server error
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: External provider error
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import ContextDev from 'context.dev';

            const client = new ContextDev({
              apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted
            });

            const response = await client.people.enrich({
              company: { name: 'Analytical Engines', domain: 'analyticalengines.example' },
              name: { first: 'Ada', last: 'Lovelace' },
              social_urls: ['https://www.linkedin.com/in/ada-lovelace/'],
            });

            console.log(response.match);
        - lang: Python
          source: |-
            import os
            from context.dev import ContextDev

            client = ContextDev(
                api_key=os.environ.get("CONTEXT_DEV_API_KEY"),  # This is the default and can be omitted
            )
            response = client.people.enrich(
                company={
                    "name": "Analytical Engines",
                    "domain": "analyticalengines.example",
                },
                name={
                    "first": "Ada",
                    "last": "Lovelace",
                },
                social_urls=["https://www.linkedin.com/in/ada-lovelace/"],
            )
            print(response.match)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/context-dot-dev/context-go-sdk\"\n\t\"github.com/context-dot-dev/context-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tresponse, err := client.People.Enrich(context.TODO(), contextdev.PersonEnrichParams{\n\t\tCompany: contextdev.PersonEnrichParamsCompany{\n\t\t\tName:   contextdev.String(\"Analytical Engines\"),\n\t\t\tDomain: contextdev.String(\"analyticalengines.example\"),\n\t\t},\n\t\tName: contextdev.PersonEnrichParamsName{\n\t\t\tFirst: contextdev.String(\"Ada\"),\n\t\t\tLast:  contextdev.String(\"Lovelace\"),\n\t\t},\n\t\tSocialURLs: []string{\"https://www.linkedin.com/in/ada-lovelace/\"},\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.Match)\n}\n"
        - lang: Ruby
          source: |-
            require "context_dev"

            context_dev = ContextDev::Client.new(api_key: "My API Key")

            response = context_dev.people.enrich

            puts(response)
        - lang: PHP
          source: >-
            <?php


            require_once dirname(__DIR__) . '/vendor/autoload.php';


            use ContextDev\Client;

            use ContextDev\Core\Exceptions\APIException;


            $client = new Client(apiKey: getenv('CONTEXT_DEV_API_KEY') ?: 'My
            API Key');


            try {
              $response = $client->people->enrich(
                company: [
                  'domain' => 'analyticalengines.example', 'name' => 'Analytical Engines'
                ],
                education: [
                  [
                    'degree' => 'x',
                    'fieldOfStudy' => 'x',
                    'graduationYear' => 1900,
                    'institution' => ['domain' => 'x', 'name' => 'x'],
                  ],
                ],
                email: 'dev@stainless.com',
                location: ['city' => 'x', 'country' => 'x', 'region' => 'x'],
                name: ['first' => 'Ada', 'last' => 'Lovelace'],
                socialURLs: ['https://www.linkedin.com/in/ada-lovelace/'],
                tags: ['production', 'team-alpha'],
                timeoutMs: 1000,
              );

              var_dump($response);
            } catch (APIException $e) {
              echo $e->getMessage();
            }
        - lang: CLI
          source: |-
            context-dev people enrich \
              --api-key 'My API Key'
components:
  schemas:
    PersonEnrichmentRequest:
      type: object
      properties:
        social_urls:
          type: array
          items:
            type: string
            format: uri
          minItems: 1
          maxItems: 20
        name:
          type: object
          properties:
            first:
              type: string
              minLength: 1
              maxLength: 100
            last:
              type: string
              minLength: 1
              maxLength: 100
          additionalProperties: false
        email:
          type: string
          maxLength: 320
          format: email
        company:
          type: object
          properties:
            name:
              type: string
              minLength: 1
              maxLength: 200
            domain:
              type: string
              minLength: 1
              maxLength: 253
          additionalProperties: false
        education:
          type: array
          items:
            type: object
            properties:
              institution:
                type: object
                properties:
                  name:
                    type: string
                    minLength: 1
                    maxLength: 200
                  domain:
                    type: string
                    minLength: 1
                    maxLength: 253
                additionalProperties: false
              degree:
                type: string
                minLength: 1
                maxLength: 200
              field_of_study:
                type: string
                minLength: 1
                maxLength: 200
              graduation_year:
                type: integer
                minimum: 1900
                maximum: 2200
            additionalProperties: false
          minItems: 1
          maxItems: 10
        location:
          type: object
          properties:
            city:
              type: string
              minLength: 1
              maxLength: 200
            region:
              type: string
              minLength: 1
              maxLength: 200
            country:
              type: string
              minLength: 1
              maxLength: 200
          additionalProperties: false
        timeoutMS:
          $ref: '#/components/schemas/TimeoutMS'
        tags:
          $ref: '#/components/schemas/RequestTags'
      additionalProperties: false
      description: >-
        Identity clues for one person. Provide a person email, a person-profile
        social URL, or both first and last name with company, education, or
        location. All supplied clues are considered together.
    PersonEnrichmentResponse:
      type: object
      properties:
        match:
          $ref: '#/components/schemas/PersonEnrichmentMatch'
        key_metadata:
          $ref: '#/components/schemas/KeyMetadata'
      required:
        - match
      additionalProperties: false
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Error message
        error_code:
          type: string
          enum:
            - INTERNAL_ERROR
            - VALID
            - NOT_FOUND
            - FORBIDDEN
            - USAGE_EXCEEDED
            - RATE_LIMITED
            - UNAUTHORIZED
            - DISABLED
            - PAID_PLAN_REQUIRED
            - INSUFFICIENT_PERMISSIONS
            - TIMEOUT_EXCEEDS_MAXIMUM
            - WEBSITE_ACCESS_ERROR
            - WEBSITE_NOT_FOUND
            - PDF_SKIPPED
            - PDF_IMAGES_ONLY
            - EXTERNAL_PROVIDER_ERROR
            - INPUT_VALIDATION_ERROR
            - ZDR_NOT_SUPPORTED
            - ZDR_NOT_ENABLED
            - FREE_EMAIL_DETECTED
            - DISPOSABLE_EMAIL_DETECTED
            - REQUEST_TIMEOUT
            - COLD_DOMAIN_TIMEOUT_TOO_LOW
            - UNSUPPORTED_CONTENT
            - CONTENT_TOO_LARGE
            - MONITOR_PAUSED
            - MONITOR_NO_WEBHOOK
            - COLLECTION_PAUSED
            - MONITOR_LIMIT_EXCEEDED
            - SEARCH_UNAVAILABLE
            - BATCH_LIMIT_EXCEEDED
            - BATCH_NOT_CANCELLABLE
            - BATCH_NOT_COMPLETED
            - IDEMPOTENCY_KEY_CONFLICT
          description: Error code indicating the type of error
        key_metadata:
          $ref: '#/components/schemas/KeyMetadata'
    KeyMetadata:
      type: object
      properties:
        credits_consumed:
          type: integer
          description: The number of credits consumed by this request.
        credits_remaining:
          type: integer
          description: >-
            The number of credits remaining for your organization after this
            request.
      required:
        - credits_consumed
        - credits_remaining
      description: >-
        Metadata about the API key used for the request. Included in every
        response whenever a valid API key is provided, even when the response
        status is not 200.
    TimeoutMS:
      type: integer
      minimum: 1000
      maximum: 300000
      description: >-
        Optional timeout in milliseconds for the request. If the request takes
        longer than this value, it will be aborted with a 408 status code.
        Maximum allowed value is 300000ms (5 minutes).
    RequestTags:
      type: array
      items:
        type: string
        minLength: 1
        maxLength: 50
      maxItems: 20
      description: >-
        Optional tags for tracking usage. Up to 20 tags, each 1 to 50
        characters.
      example:
        - production
        - team-alpha
    PersonEnrichmentMatch:
      oneOf:
        - $ref: '#/components/schemas/PersonEnrichmentCandidateMatch'
        - $ref: '#/components/schemas/PersonEnrichmentNotFoundMatch'
      discriminator:
        propertyName: status
        mapping:
          candidate:
            $ref: '#/components/schemas/PersonEnrichmentCandidateMatch'
          not_found:
            $ref: '#/components/schemas/PersonEnrichmentNotFoundMatch'
    PersonEnrichmentCandidateMatch:
      type: object
      properties:
        status:
          type: string
          enum:
            - candidate
        score:
          type: integer
          minimum: 0
          maximum: 100
        person:
          type: object
          properties:
            name:
              type: object
              properties:
                full:
                  type: string
                first:
                  type: string
                last:
                  type: string
              additionalProperties: false
            email:
              type: string
              format: email
            avatar_url:
              type: string
              pattern: ^https:\/\/media\.brand\.dev\/pfp\/[0-9a-f-]{36}$
            bio:
              type: string
            location:
              type: object
              properties:
                display:
                  type: string
                city:
                  type: string
                region:
                  type: string
                country:
                  type: string
                country_code:
                  type: string
              additionalProperties: false
            social_urls:
              type: array
              items:
                type: string
                format: uri
            website_urls:
              type: array
              items:
                type: string
                format: uri
            current_role:
              type: object
              properties:
                title:
                  type: string
                organization:
                  type: object
                  properties:
                    name:
                      type: string
                    domain:
                      type: string
                  required:
                    - name
                  additionalProperties: false
                location:
                  type: string
                description:
                  type: string
                start_date:
                  type: object
                  properties:
                    year:
                      type: integer
                    month:
                      type: integer
                      minimum: 1
                      maximum: 12
                    day:
                      type: integer
                      minimum: 1
                      maximum: 31
                  required:
                    - year
                  additionalProperties: false
                end_date:
                  type: object
                  properties:
                    year:
                      type: integer
                    month:
                      type: integer
                      minimum: 1
                      maximum: 12
                    day:
                      type: integer
                      minimum: 1
                      maximum: 31
                  required:
                    - year
                  additionalProperties: false
                is_current:
                  type: boolean
              required:
                - title
                - organization
              additionalProperties: false
            experience:
              type: array
              items:
                type: object
                properties:
                  title:
                    type: string
                  organization:
                    type: object
                    properties:
                      name:
                        type: string
                      domain:
                        type: string
                    required:
                      - name
                    additionalProperties: false
                  location:
                    type: string
                  description:
                    type: string
                  start_date:
                    type: object
                    properties:
                      year:
                        type: integer
                      month:
                        type: integer
                        minimum: 1
                        maximum: 12
                      day:
                        type: integer
                        minimum: 1
                        maximum: 31
                    required:
                      - year
                    additionalProperties: false
                  end_date:
                    type: object
                    properties:
                      year:
                        type: integer
                      month:
                        type: integer
                        minimum: 1
                        maximum: 12
                      day:
                        type: integer
                        minimum: 1
                        maximum: 31
                    required:
                      - year
                    additionalProperties: false
                  is_current:
                    type: boolean
                required:
                  - title
                  - organization
                additionalProperties: false
            education:
              type: array
              items:
                type: object
                properties:
                  institution:
                    type: object
                    properties:
                      name:
                        type: string
                      domain:
                        type: string
                    required:
                      - name
                    additionalProperties: false
                  degree:
                    type: string
                  field_of_study:
                    type: string
                  description:
                    type: string
                  start_date:
                    type: object
                    properties:
                      year:
                        type: integer
                      month:
                        type: integer
                        minimum: 1
                        maximum: 12
                      day:
                        type: integer
                        minimum: 1
                        maximum: 31
                    required:
                      - year
                    additionalProperties: false
                  end_date:
                    type: object
                    properties:
                      year:
                        type: integer
                      month:
                        type: integer
                        minimum: 1
                        maximum: 12
                      day:
                        type: integer
                        minimum: 1
                        maximum: 31
                    required:
                      - year
                    additionalProperties: false
                required:
                  - institution
                additionalProperties: false
            skills:
              type: array
              items:
                type: string
          required:
            - social_urls
            - website_urls
            - experience
            - education
            - skills
          additionalProperties: false
      required:
        - status
        - score
        - person
      additionalProperties: false
      title: Candidate match
      description: The highest-scoring person candidate.
    PersonEnrichmentNotFoundMatch:
      type: object
      properties:
        status:
          type: string
          enum:
            - not_found
        score:
          type: 'null'
        person:
          type: 'null'
      required:
        - status
        - score
        - person
      additionalProperties: false
      title: No match
      description: No usable person candidate was found.
  headers:
    RateLimitLimit:
      description: >-
        Maximum requests allowed in the current fixed one-minute window.
        Returned when the authenticated API key has a per-minute rate limit.
      schema:
        type: integer
        minimum: 1
    RateLimitRemaining:
      description: >-
        Requests remaining in the current fixed one-minute window. Returned when
        the authenticated API key has a per-minute rate limit.
      schema:
        type: integer
        minimum: 0
    RateLimitReset:
      description: >-
        Unix timestamp in seconds when the current rate-limit window resets.
        Returned when the authenticated API key has a per-minute rate limit.
      schema:
        type: integer
  responses:
    RateLimited:
      description: Rate limit exceeded
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        Retry-After:
          description: Seconds until the per-minute rate limit window resets
          schema:
            type: integer
            minimum: 1
            maximum: 60
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                description: Error message
              error_code:
                type: string
                enum:
                  - RATE_LIMITED
                description: Error code indicating the rate limit was exceeded
              key_metadata:
                $ref: '#/components/schemas/KeyMetadata'
            required:
              - message
              - error_code
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Bearer authentication header of the form `Bearer <API_KEY>`, where
        `<API_KEY>` is your api key.

````