--- title: "Enrich a person" method: POST path: "/people/enrich" tags: ["People"] --- # Enrich a person `POST /people/enrich` ## Request - Base URL: `https://api.context.dev/v1` - URL: `https://api.context.dev/v1/people/enrich` - Auth: HTTP bearer Find a person from identity clues and return their profile with a match score. Available on all plans; free or disposable email addresses return 422. ## 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[]: Public profile URLs for the person. A person-profile URL can identify the person without a name. - `name` object: Person name. Without an email or person-profile URL, provide both first and last name plus company, education, or location. - `first` string: First or given name. - `last` string: Last or family name. - `email` string, email: Email address of the person to find. - `company` object: Company context to help identify the person. Provide a name or domain. - `name` string: Name of a company associated with the person. - `domain` string: Website domain of a company associated with the person. - `education` object[]: Education history to help distinguish people with similar names. - `institution` object: School or university, identified by name or domain. - `name` string: Name of the school or university. - `domain` string: Website domain of the school or university. - `degree` string: Degree or qualification earned. - `field_of_study` string: Subject or major studied. - `graduation_year` integer: Four-digit graduation year. - `location` object: Location context to help identify the person. Provide a city, region, or country. - `city` string: City associated with the person. - `region` string: State, province, or region associated with the person. - `country` string: Country associated with the person. - `timeoutOpts` PartialTimeout: Request deadline and what to return when it passes. - `milliseconds` integer, required: Deadline in milliseconds. - `behavior` 'fail' | 'return-partial': "fail" returns 408 at the deadline. "return-partial" returns available results; inspect the response’s partial flag. - `zdr` 'enabled' | 'disabled': `enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR. - `tags` string[]: Labels for filtering usage in the dashboard. ## Response `200` The highest-scoring candidate, including weak matches, or a not-found result when no usable candidate exists. - PersonEnrichmentResponse - `partial` boolean: True when the timeout ended processing and this response contains the usable data completed so far. Unfinished fields are omitted. - `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 - `current_role_status` 'present' | 'none' | 'unknown', required: Whether the person's current role is known. `present` — current_role is populated. `none` — the work history explicitly shows every role has ended. `unknown` — our data sources could not confirm either way; treat a missing current_role as unverified rather than vacant. - `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 - `last_updated` string: When the underlying profile data last changed in our data sources (ISO 8601). Omitted when unknown. - `checked_at` string: When we last refreshed this profile from our data sources (ISO 8601). - PersonEnrichmentNotFoundMatch: No usable person candidate was found. - `status` 'not_found', required - `score` unknown, required - `person` unknown, required - `key_metadata` KeyMetadata: Credits this request used and your remaining balance. - `credits_consumed` integer, required: Credits charged for this request. - `credits_remaining` integer, required: Credits remaining for your organization. - `request_id` string, uuid, required: Unique ID of this request, also in `X-Request-Id`. Include it when contacting support. ## Other responses - `400`: Bad request - Insufficient or invalid identity clues - `401`: Unauthorized - Invalid or missing API key - `402`: Insufficient credits (`USAGE_EXCEEDED`); authentication is valid. Retry once funded. Legacy deployments may return 401. - `403`: API key permissions or organization settings do not allow this request. - `408`: Request timeout - `422`: Free or disposable email domain. - `429`: Rate limit exceeded. Organization concurrency rejections include structured error_data and subscription settings; follow Retry-After before retrying. - `500`: Internal server error ## Changes - **2026-10-21** `61627728926b`: 6 warning - added the new `NO_PUBLISHED_MARKDOWN` enum value to the `error_code` response property for the response status `400` - added the new `NO_PUBLISHED_MARKDOWN` enum value to the `error_code` response property for the response status `401` - added the new `NO_PUBLISHED_MARKDOWN` enum value to the `error_code` response property for the response status `402` - added the new `NO_PUBLISHED_MARKDOWN` enum value to the `error_code` response property for the response status `403` - …2 more - **2026-10-19** `4ddcf49b9fe5`: 7 info - added the non-success response with the status `402` - added the optional property `error_data` to the response with the `400` status - added the optional property `error_data` to the response with the `401` status - added the optional property `error_data` to the response with the `403` status - …3 more - **2026-10-16** `2125f3e94e52`: 1 info - endpoint added [Operation history](https://skmtc.dev/context/apis/brand-api/changes/people/enrich/post.md) --- [API](https://skmtc.dev/context/apis/brand-api.md) · [All operations](https://skmtc.dev/context/apis/brand-api/llms.txt) · [OpenAPI document](https://skmtc.dev/context/apis/brand-api/revisions/9e2ab7841fb1?raw)