---
title: "Enrich Person"
method: POST
path: "/people/enrich"
tags: ["People"]
---

# Enrich Person

`POST /people/enrich`

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.

## Request body

- PersonEnrichmentRequest — 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.
  - `social_urls` string[]
  - `name` object
    - `first` string
    - `last` string
  - `email` string, email
  - `company` object
    - `name` string
    - `domain` string
  - `education` object[]
    - `institution` object
      - `name` string
      - `domain` string
    - `degree` string
    - `field_of_study` string
    - `graduation_year` integer
  - `location` object
    - `city` string
    - `region` string
    - `country` string
  - `timeoutMS` integer — 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).
  - `tags` string[] — Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters.

## Response `200`

The highest-scoring candidate, including weak matches, or a not-found result when no usable candidate exists.

- PersonEnrichmentResponse
  - `match` union, required
    - PersonEnrichmentCandidateMatch — The highest-scoring person candidate.
      - `status` 'candidate', required
      - `score` integer, required
      - `person` object, required
        - `name` object
          - `full` string
          - `first` string
          - `last` string
        - `email` string, email
        - `avatar_url` string
        - `bio` string
        - `location` object
          - `display` string
          - `city` string
          - `region` string
          - `country` string
          - `country_code` string
        - `social_urls` string[], required
        - `website_urls` string[], required
        - `current_role` object
          - `title` string, required
          - `organization` object, required
            - `name` string, required
            - `domain` string
          - `location` string
          - `description` string
          - `start_date` object
            - `year` integer, required
            - `month` integer
            - `day` integer
          - `end_date` object
            - `year` integer, required
            - `month` integer
            - `day` integer
          - `is_current` boolean
        - `experience` object[], required
          - `title` string, required
          - `organization` object, required
            - `name` string, required
            - `domain` string
          - `location` string
          - `description` string
          - `start_date` object
            - `year` integer, required
            - `month` integer
            - `day` integer
          - `end_date` object
            - `year` integer, required
            - `month` integer
            - `day` integer
          - `is_current` boolean
        - `education` object[], required
          - `institution` object, required
            - `name` string, required
            - `domain` string
          - `degree` string
          - `field_of_study` string
          - `description` string
          - `start_date` object
            - `year` integer, required
            - `month` integer
            - `day` integer
          - `end_date` object
            - `year` integer, required
            - `month` integer
            - `day` integer
        - `skills` string[], required
    - PersonEnrichmentNotFoundMatch — No usable person candidate was found.
      - `status` 'not_found', required
      - `score` unknown, required
      - `person` unknown, required
  - `key_metadata` KeyMetadata — 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.
    - `credits_consumed` integer, required — The number of credits consumed by this request.
    - `credits_remaining` integer, required — The number of credits remaining for your organization after this request.

## Other responses

- `400` — Bad request - Insufficient or invalid identity clues
- `401` — Unauthorized - Invalid or missing API key
- `403` — Forbidden - Insufficient permissions or usage limit exceeded
- `408` — Request timeout
- `422` — Unprocessable Entity - Free email or disposable email detected
- `429` — Rate limit exceeded
- `500` — Internal server error
- `502` — External provider error

---

[API](https://skmtc.net/context/apis/context-dev.md) · [All operations](https://skmtc.net/context/apis/context-dev/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/context/context-dev/versions/182f532c2552/schema)