People Search APIs

People Search APIs let you find and manage individual contacts using AI-powered query understanding, criteria-driven refinement, and asynchronous workflow execution.

Overview

The People Search system runs asynchronous workflows so you can start or refine contact searches, monitor progress, access results, and stop active runs.

The workflow includes:

Start or Continue – Begin a new people search with a prompt, or extend an existing workflow by supplying its thread_id and a total_target
Monitor status – Poll GET /status/{thread_id} with the thread_id returned from start or continue to fetch the current workflow snapshot (criteria, table structure, rows, state)
Get results & lists – Use the Company Search Get Lists and Get Search Result endpoints today (people results are included). Dedicated GET /people-search/getLists and GET /people-search/getSearchResult/{thread_id} routes are coming soon.
People enrichment – Start or stop asynchronous enrichment workflows on people search results
Stop – Cancel an in-flight people workflow using its thread_id
Search people – Query contacts directly from MongoDB using Atlas Search with structured path filters

Base URL: https://chordian-core.chordian.ai

Authentication: Bearer token (HTTPBearer) or API key cookie (APIKeyCookie). Send your API key in the header: Authorization: Bearer <api-key>.

Start People Search

Start a people search workflow.

The body must include a string prompt. The API forwards that JSON to the agent service via celery_task.execute_function with function_name="start_people_workflow". The workflow runs in the background; use the returned thread_id to poll status.

POST /people-search/start

Authentication: Authorization: Bearer <api-key>

Request Body

{
  "list_description": "VP Engineering leaders in fintech",
  "list_name": "Q3 prospects",
  "prompt": "Find VP-level engineering leaders at Series B fintech companies in the US",
  "search_mode": "fast"
}

Field	Type	Required	Description
`prompt`	string	✅	Natural-language description of the people you want to find.
`list_description`	string	❌	Human-readable description for the resulting list.
`list_name`	string	❌	Name for the resulting list.
`search_mode`	string	❌	Search mode (e.g. `fast`).

Successful Response (200 OK)

{
  "success": true,
  "message": "string",
  "thread_id": "string",
  "status": "processing"
}

Field	Type	Description
`success`	boolean	`true` when the workflow was started successfully.
`message`	string	Human-readable status message.
`thread_id`	string	Workflow thread identifier. Pass this to Get People Search Status (`GET /people-search/status/{thread_id}`), or use with Continue / Stop.
`status`	string	Workflow state (e.g. `processing`).

Validation Error (422)

{
  "status_code": 422,
  "message": "Request validation failed",
  "errors": [
    {
      "field": "body.prompt",
      "message": "Field required",
      "type": "missing"
    }
  ],
  "data": null
}

Example

curl -X POST "https://chordian-core.chordian.ai/people-search/start" \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "list_description": "VP Engineering leaders in fintech",
    "list_name": "Q3 prospects",
    "prompt": "Find VP-level engineering leaders at Series B fintech companies in the US",
    "search_mode": "fast"
  }'

Continue People Search

Continue an existing people search workflow.

The body must include thread_id and total_target. The API forwards that JSON to the agent service via celery_task.execute_function with function_name="continue_people_workflow".

POST /people-search/continue

Authentication: Authorization: Bearer <api-key>

Request Body

{
  "thread_id": "thread_abc123",
  "total_target": 200
}

Field	Type	Required	Description
`thread_id`	string	✅	Identifier of the existing workflow thread to continue (the `thread_id` returned by Start People Search).
`total_target`	integer	✅	Target total number of people the workflow should aim to collect.

Successful Response (200 OK)

{
  "success": true,
  "thread_id": "string",
  "status": "continuing"
}

Field	Type	Description
`success`	boolean	`true` when the continue request was accepted.
`thread_id`	string	Workflow thread identifier. Pass this to Get People Search Status (`GET /people-search/status/{thread_id}`).
`status`	string	Workflow state (e.g. `continuing`).

Validation Error (422)

{
  "status_code": 422,
  "message": "Request validation failed",
  "errors": [
    {
      "field": "body.thread_id",
      "message": "Field required",
      "type": "missing"
    },
    {
      "field": "body.total_target",
      "message": "Field required",
      "type": "missing"
    }
  ],
  "data": null
}

Example

curl -X POST "https://chordian-core.chordian.ai/people-search/continue" \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "thread_id": "thread_xyz789",
    "total_target": 200
  }'

Get People Search Status

Poll the status of a previously started people workflow. Returns a snapshot of the workflow (criteria, table structure, rows, etc.) for the given thread_id.

GET /people-search/status/{thread_id}

Authentication: Authorization: Bearer <api-key>

Path Parameters

Parameter	Type	Required	Description
`thread_id`	string	✅	People workflow thread identifier (the `thread_id` returned by Start or Continue).

Successful Response (200 OK)

A full snapshot of the workflow — overall status, search criteria, the result table (columns + rows), collected records, and progress counters.

{
  "success": true,
  "thread_id": "string",
  "current_step": "string",
  "category": "string",
  "criteria": [
    {
      "name": "string",
      "value": "string",
      "column_name": "string",
      "columnType": "string",
      "description": "string",
      "type": "string",
      "width": 0,
      "maxWidth": 0,
      "minWidth": 0
    }
  ],
  "error_message": "string",
  "total_target": 0,
  "table_structure": {
    "columns": [
      {
        "id": "string",
        "header": "string",
        "type": "fixed",
        "width": 0,
        "required": true,
        "columnType": "string",
        "dataType": "string",
        "maxWidth": 0,
        "minWidth": 0
      }
    ],
    "rows": [
      {
        "id": "string",
        "cells": {
          "additionalProp1": {
            "row_id": "string",
            "column_id": "string",
            "value": "string",
            "status": "string",
            "metadata": {
              "additionalProp1": {}
            },
            "expandable": false
          }
        },
        "step_source": "string",
        "metadata": {
          "additionalProp1": {}
        }
      }
    ],
    "total_target": 0,
    "current_count": 0
  },
  "all_companies": [
    {
      "additionalProp1": {}
    }
  ],
  "step_companies": {
    "additionalProp1": {}
  },
  "title": "string",
  "description": "string",
  "goal": "string",
  "processed_companies": [
    "string"
  ]
}

Top-level fields

Field	Type	Description
`success`	boolean	`true` when the snapshot was produced successfully. Check `error_message` when `false`.
`thread_id`	string	Identifier of this workflow thread.
`current_step`	string	Name of the step the workflow is currently executing.
`category`	string	Workflow category / classification assigned by the agent.
`criteria`	array<Criterion>	Filtering / scoring criteria (see Criterion).
`error_message`	string	Error description when the workflow fails; empty or null otherwise.
`total_target`	integer	Target total number of records the workflow aims to collect.
`table_structure`	object<TableStructure>	Schema and current contents of the result table (see TableStructure).
`all_companies`	array<object>	All records discovered across the workflow (wire field name; each item is an open object).
`step_companies`	object	Map of step name → records surfaced in that step (wire field name).
`title`	string	Human-readable title for the workflow / result set.
`description`	string	Human-readable description of the workflow / result set.
`goal`	string	Goal statement for the workflow.
`processed_companies`	array<string>	Identifiers of records the workflow has processed so far (wire field name).

Criterion (item of `criteria[]`)

Field	Type	Description
`name`	string	Criterion name.
`value`	string	Current value / target for the criterion.
`column_name`	string	Result-table column this criterion maps to.
`columnType`	string	UI column-type hint.
`description`	string	Human-readable description.
`type`	string	Internal criterion type.
`width`	integer	Default column width (pixels).
`maxWidth`	integer	Maximum column width.
`minWidth`	integer	Minimum column width.

TableStructure (`table_structure`)

Field	Type	Description
`columns`	array<Column>	Column definitions (see Column).
`rows`	array<Row>	Rows collected so far (see Row).
`total_target`	integer	Target row count for this table.
`current_count`	integer	Number of rows currently in the table.

Column (item of `table_structure.columns[]`)

Field	Type	Description
`id`	string	Stable column identifier (used as `cells` key on each row).
`header`	string	Display label for the column.
`type`	string	Column type — typically `fixed` or dynamic-criterion columns.
`width`	integer	Default column width (pixels).
`required`	boolean	Whether the column must be populated for a complete row.
`columnType`	string	UI column-type hint.
`dataType`	string	Underlying data type for cell values.
`maxWidth`	integer	Maximum column width.
`minWidth`	integer	Minimum column width.

Row (item of `table_structure.rows[]`)

Field	Type	Description
`id`	string	Stable row identifier.
`cells`	object<string, Cell>	Map of column id → cell value (see Cell).
`step_source`	string	Workflow step that produced this row.
`metadata`	object	Arbitrary per-row metadata.

Cell (value in `Row.cells`)

Field	Type	Description
`row_id`	string	Parent row identifier.
`column_id`	string	Column this cell belongs to.
`value`	string	Cell value, serialized as a string.
`status`	string	Cell status (e.g. `pending`, `loaded`, `error`).
`metadata`	object	Arbitrary per-cell metadata.
`expandable`	boolean	`true` when a drill-down view is available.

Validation Error (422)

{
  "status_code": 422,
  "message": "Validation Error",
  "errors": [
    {
      "field": "path.thread_id",
      "message": "Field required",
      "type": "missing"
    }
  ],
  "data": null
}

Example

curl "https://chordian-core.chordian.ai/people-search/status/thread_abc123" \
  -H "Authorization: Bearer <api-key>"

Stop People Search

Stop a running people-search workflow.

The path thread_id is forwarded to the agent service via celery_task.execute_function with function_name="stop_people_workflow".

POST /people-search/stop/{thread_id}

Authentication: Authorization: Bearer <api-key>

Path Parameters

Parameter	Type	Required	Description
`thread_id`	string	✅	People workflow thread identifier (the `thread_id` returned by Start or Continue).

Successful Response (200 OK)

{
  "success": true,
  "thread_id": "string",
  "status": "stopping",
  "message": "string"
}

Field	Type	Description
`success`	boolean	`true` when the stop request was accepted.
`thread_id`	string	Workflow thread identifier that is being stopped.
`status`	string	Workflow state (e.g. `stopping`).
`message`	string	Human-readable status message.

Validation Error (422)

{
  "status_code": 422,
  "message": "Validation Error",
  "errors": [
    {
      "field": "path.thread_id",
      "message": "Field required",
      "type": "missing"
    }
  ],
  "data": null
}

Example

curl -X POST "https://chordian-core.chordian.ai/people-search/stop/thread_abc123" \
  -H "Authorization: Bearer <api-key>"

Start People Enrichment

Start a people enrichment workflow on an existing people search thread.

POST /people-search/start-enrichment

Authentication: Authorization: Bearer <api-key>

Request Body

{
  "thread_id": "thread_abc123",
  "column_name": "string"
}

Field	Type	Required	Description
`thread_id`	string	✅	Workflow thread identifier for the people search to enrich.
`column_name`	string	✅	Column to enrich in the workflow result table.

Successful Response (200 OK)

{}

Field	Type	Description
(response)	object	Enrichment task details returned by the agent service.

Validation Error (422)

{
  "status_code": 422,
  "message": "Request validation failed",
  "errors": [
    {
      "field": "body.thread_id",
      "message": "Field required",
      "type": "missing"
    },
    {
      "field": "body.column_name",
      "message": "Field required",
      "type": "missing"
    }
  ],
  "data": null
}

Example

curl -X POST "https://chordian-core.chordian.ai/people-search/start-enrichment" \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "thread_id": "thread_xyz789",
    "column_name": "email"
  }'

Stop People Enrichment

Stop a running people enrichment workflow.

POST /people-search/stop-enrichment/{thread_id}

Authentication: Authorization: Bearer <api-key>

Path Parameters

Parameter	Type	Required	Description
`thread_id`	string	✅	People workflow thread identifier for the enrichment run to stop.

Successful Response (200 OK)

{}

Field	Type	Description
(response)	object	Enrichment task details returned by the agent service.

Validation Error (422)

{
  "status_code": 422,
  "message": "Validation Error",
  "errors": [],
  "data": null
}

Example

curl -X POST "https://chordian-core.chordian.ai/people-search/stop-enrichment/thread_abc123" \
  -H "Authorization: Bearer <api-key>"

Fetching lists and results (via Company Search)

Coming soon: GET /people-search/getLists and GET /people-search/getSearchResult/{thread_id} are not available yet. Use the Company Search endpoints below to fetch lists and thread results for people workflows today — responses include people search data as well as company data.

Get Lists

Get all lists for the current tenant (company and people workflows).

See Get Lists in Company Search APIs for the full reference.

GET /company-search/getLists

Authentication: Authorization: Bearer <api-key>

Successful Response (200 OK)

{
  "success": true,
  "data": [
    {
      "id": "string",
      "listLinkID": "string",
      "createdAt": "string",
      "listDescription": "string",
      "listName": "string",
      "listStatus": "string",
      "listType": "string",
      "noOfRecords": 0,
      "title": "string",
      "subtitle": "string",
      "author": 0,
      "type": "string"
    }
  ],
  "total": 0
}

Field	Type	Description
`success`	boolean	`true` when lists were retrieved successfully.
`data`	array<ListItem>	List records for the current tenant (see ListItem). Includes people and company lists.
`total`	integer	Total number of lists returned.

ListItem (item of `data[]`)

Field	Type	Description
`id`	string	List identifier.
`listLinkID`	string	Linked list ID.
`createdAt`	string	ISO timestamp when the list was created.
`listDescription`	string	List description.
`listName`	string	List name.
`listStatus`	string	Current list status.
`listType`	string	List type classification.
`noOfRecords`	integer	Number of records in the list.
`title`	string	Display title.
`subtitle`	string	Display subtitle.
`author`	integer	Author identifier.
`type`	string	Type label.

Example

curl "https://chordian-core.chordian.ai/company-search/getLists" \
  -H "Authorization: Bearer <api-key>"

Get Search Result

Get the search result for a given thread (use the thread_id from your people search workflow).

See Get Search Result in Company Search APIs for the full reference.

GET /company-search/getSearchResult/{thread_id}

Authentication: Authorization: Bearer <api-key>

Path Parameters

Parameter	Type	Required	Description
`thread_id`	string	✅	Workflow thread identifier (e.g. from Start People Search)

Successful Response (200 OK)

{
  "success": true,
  "thread_id": "string",
  "list_id": "string",
  "status": "string",
  "list_name": "string",
  "list_description": "string",
  "list_type": "string",
  "total_target": 0,
  "criteria": [
    {
      "name": "string",
      "value": "string",
      "column_name": "string",
      "type": "string"
    }
  ],
  "results": [
    {
      "additionalProp1": {}
    }
  ],
  "count": 0,
  "created_at": "string",
  "updated_at": "string"
}

Field	Type	Description
`success`	boolean	`true` when the result was retrieved successfully.
`thread_id`	string	Workflow thread identifier.
`list_id`	string	Associated list identifier.
`status`	string	Result / workflow status.
`list_name`	string	Name of the list.
`list_description`	string	Description of the list.
`list_type`	string	List type classification.
`total_target`	integer	Target number of records for this search.
`criteria`	array<object>	Criteria used for the search (each item has `name`, `value`, `column_name`, `type`).
`results`	array<object>	Result rows — includes people records from people search workflows (open shape per item).
`count`	integer	Number of results returned.
`created_at`	string	ISO timestamp when the result was created.
`updated_at`	string	ISO timestamp when the result was last updated.

Example

curl "https://chordian-core.chordian.ai/company-search/getSearchResult/thread_abc123" \
  -H "Authorization: Bearer <api-key>"

Search People

Search people from MongoDB using Atlas Search. Pass one or more field name values in the path array to control which attributes are matched against your query.

For nested fields, use the full dot-notation name from the table below (for example, personalInfo.linkedin_url or currentJobInfo.current_employer).

Searchable attributes

Use the Name column values in your request path array.

Name	Label	Description
`fullName`	Name	The full name of the contact.
`personalInfo.profileImage`	Profile Image	URL or reference to the contact’s profile image.
`personalInfo.linkedin_url`	LinkedIn	LinkedIn profile URL of the contact.
`personalInfo.location`	Location	The contact’s location, typically city, region, or country.
`position`	Current Job Title	The contact’s current job title or role.
`currentJobInfo.current_employer`	Company Name	The name of the company where the person currently works.
`currentJobInfo.current_employer_id`	Current Employer ID	Unique identifier for the person’s current employer.
`currentJobInfo.current_employer_domain`	Current Employer Domain	The official website domain of the organization where the person is currently employed.
`currentJobInfo.current_employer_website`	Current Employer Website	The official website of the organization where the person currently works.
`currentJobInfo.current_employer_linkedin_url`	Current Employer LinkedIn URL	The LinkedIn company page URL of the person’s current employer.
`personalInfo.birth_year`	Birth Year	The year in which the individual was born.
`personalInfo.region_latitude`	Latitude	Geographic latitude coordinate for the individual’s region or location.
`personalInfo.region_longitude`	Longitude	Geographic longitude coordinate for the individual’s region or location.
`personalInfo.city`	City	The city where the individual currently resides.
`personalInfo.region`	Region	The state, province, or broader geographic region where the individual resides.
`personalInfo.country`	Country	The country where the individual resides or is associated with.
`personalInfo.country_code`	Country Code	ISO country code (e.g. alpha-2) representing the individual’s country.
`personalInfo.education`	Education	Academic background, including degrees, institutions, and fields of study.
`skills`	Skills	Professional skills and expertise, including technical, soft, and domain-specific competencies.
`links.angellist`	AngelList URL	The contact’s AngelList profile URL.
`links.twitter`	Twitter	The Twitter profile URL or handle of the contact.
`links.quora`	Quora URL	The Quora profile URL of the contact.
`links.crunchbase`	Crunchbase URL	The Crunchbase profile URL with professional and investment-related information.
`links.facebook`	Facebook URL	The Facebook profile URL of the contact.
`recommended_email`	Email	Recommended email address for contacting the individual.
`personalInfo.domain`	Domain	Primary website domain associated with the contact or their current employer.
`currentJobInfo.company_city`	Company City	The city where the person’s current company is located.
`currentJobInfo.company_region`	Company Region	The region or state where the person’s current company is based.
`currentJobInfo.company_country`	Company Country	The country where the person’s current company is headquartered or operates.
`personalInfo.seniority`	Seniority	Job level or position hierarchy within an organization (e.g. entry, manager, executive).
`personalInfo.gender`	Gender	The identified or reported gender of the individual.
`personalInfo.timezoneId`	Time Zone ID	Time zone identifier (e.g. America/New_York, Asia/Kolkata) for the contact.
`experiences.company`	Experience Company	Companies where the individual has gained professional experience.
`experiences.duration`	Experience Duration	Duration of employment at a past company, typically in months or years.
`experiences.positions`	Experience Positions	Job titles or roles held at previous workplaces.
`experiences.title`	Experience Title	Official job titles held during past work experiences.
`experiences.subtitle`	Experience Subtitle	Secondary title or brief description for a past role.
`experiences.location`	Experience Location	City, region, or country where a past role was based.
`experiences.description`	Experience Description	Summary of responsibilities, achievements, and tasks in a past role.
`experiences.startTime`	Experience Start Time	Date when the individual began a specific past role.
`experiences.endTime`	Experience End Time	Date when the individual ended a specific past role.
`experiences.socialUrl`	Experience Social URL	Social or professional profile link associated with a past role or company.
`education.title`	Education Title	Degree or qualification name (e.g. Bachelor of Science).
`education.subtitle`	Education Subtitle	Field of study, specialization, or program focus.
`education.meta`	Education Meta	Supplementary education details such as honors, activities, or projects.
`education.institutionName`	Education Institution	Name of the school, college, or university attended.
`education.socialUrl`	Education Social URL	Social profile link associated with an educational institution or record.
`education.degree`	Education Degree	Formal academic credential earned (e.g. Bachelor’s, Master’s, PhD).
`personalInfo.certifications`	Certifications	Professional certifications validating skills or training in a field.
`personalInfo.courses`	Courses	Courses or training programs the individual has completed.
`languages.name`	Languages	Languages the individual speaks, often with proficiency level.
`personalInfo.groups`	Groups	Professional or interest-based groups the contact belongs to.
`personalInfo.socialConnections`	Social Connections	Network of contacts on social and professional platforms.
`personalInfo.coverImageUrl`	Cover Image URL	URL of the contact’s cover or banner image on a profile.
`personalInfo.volunteering`	Volunteering	Unpaid service activities, organizations, and causes the contact supports.
`phone`	Phone	Phone number(s) associated with the contact.
`personalInfo.state`	State	State or province where the contact is located.
`personalInfo.stateCode`	State Code	Abbreviated state or region code for the contact’s location.
`personalInfo.bio`	Bio	Short biography summarizing the contact’s background and professional focus.
`personalInfo.avatar`	Avatar	Avatar or profile image URL for the contact.
`links.github`	GitHub	GitHub profile URL of the contact.
`links.googlePlus`	Google Plus	Google Plus profile URL of the contact.
`current_work_email`	Work Email	Professional email address for work-related communication.
`current_personal_email`	Personal Email	Personal email address for non-work communication.
`healthCare.npi_number`	NPI Number	National Provider Identifier (NPI)—unique 10-digit ID for U.S. healthcare providers.
`healthCare.credentials`	NPI Credentials	Professional credentials linked to the provider’s NPI profile.
`healthCare.license_number`	NPI License Number	Professional license information linked to the NPI profile.
`healthCare.specialization`	NPI Specialization	Medical specialty or taxonomy classification on the NPI profile.
`education.start`	Education Started	Date when the education program started.
`education.end`	Education Ended	Date when the education program ended.
`about`	About	Free-text summary about the person.
`currentJobInfo.company_size`	Current Company Size	Number of employees at the person’s current company.
`currentJobInfo.company_founded`	Current Company Founded	Year the person’s current company was founded.
`currentJobInfo.company_industry`	Current Company Industry	Industry or sector of the person’s current company.
`currentJobInfo.current_company_linkedin`	Current Company LinkedIn	LinkedIn URL of the person’s current company.
`currentJobInfo.current_company_facebook`	Current Company Facebook	Facebook page URL of the person’s current company.
`currentJobInfo.current_company_twitter`	Current Company Twitter	X (Twitter) profile URL of the person’s current company.
`currentJobInfo.current_company_type`	Current Company Type	Ownership or structure type of the current employer (e.g. private, public).
`currentJobInfo.current_company_ticker`	Current Company Ticker	Stock ticker symbol if the current employer is publicly traded.
`currentJobInfo.current_compay_employees`	Current Company Employees	Total employee count at the person’s current company.
`currentJobInfo.current_company_revenue`	Current Company Revenue	Revenue of the person’s current company for a given period.
`currentJobInfo.current_company_total_funding`	Current Company Total Funding	Total external investment raised by the person’s current company.
`personalInfo.postal_code`	Postal Code	ZIP or postal code for the contact’s address.
`salary`	Salary	Inferred or estimated salary range for the contact.
`interests`	Interests	Topics or activities the person is likely interested in based on profile and behavior signals.
`experiences.size`	Experience Company Size	Employee count at companies from past work experience.
`experiences.companyFounded`	Company Founded	Year a past employer company was founded.
`experiences.companyIndustry`	Company Industry	Industry sector of a past employer.
`experiences.experienceRegion`	Experience Region	Geographic regions where the person has worked.
`experiences.experienceStreetAddress`	Experience Company Street Address	Street-level address of a past employer’s office.
`experiences.experiencePostalCode`	Experience Company Postal Code	Postal code of a past employer’s office location.
`experiences.experienceLatitude`	Experience Company Latitude	Latitude coordinate of a past employer’s location.
`experiences.experienceLongitude`	Experience Company Longitude	Longitude coordinate of a past employer’s location.
`experiences.experineceCompanyLinkedin`	Experience Company LinkedIn	LinkedIn URL of a company from past work experience.
`experiences.experineceCompanyFacebook`	Experience Company Facebook	Facebook page URL of a past employer.
`experiences.experineceCompanyTwitter`	Experience Company Twitter	X (Twitter) URL of a past employer.
`experiences.experineceCompayWebsite`	Experience Company Website	Official website URL of a past employer.
`experiences.experineceCompanyTicker`	Experience Company Ticker	Stock ticker symbol of a past employer, if publicly traded.
`experiences.experineceCompanyType`	Experience Company Type	Ownership or structure type of a past employer company.
`education.location`	Education Institution Location	Geographic location of an educational institution attended.
`education.country`	Education Institution Country	Country where the educational institution is located.
`education.institutionLinkedin`	Education Institution LinkedIn	LinkedIn page URL of an educational institution.
`education.facebook_url`	Education Institution Facebook	Facebook page URL of an educational institution.
`education.twitter_url`	Education Institution Twitter	X (Twitter) account URL of an educational institution.
`education.website`	Education Website	Official website URL of an educational institution.
`education.domain`	Education Institution Domain	Internet domain of an educational institution.
`certifications.title`	Certifications Title	Name of a professional certification earned.
`certifications.startDate`	Certifications Start Date	Date when a certification program began.
`certifications.endDate`	Certifications End Date	Date when a certification was completed.
`certifications.name`	Certifications Name	Official title of a certification earned or in progress.

POST /people-search/search

Authentication: Authorization: Bearer <api-key>

Request Body

{
  "fuzzy_max_edits": 2,
  "limit": 10,
  "path": ["fullName", "personalInfo.linkedin_url"],
  "query": "Jane Smith"
}

Field	Type	Required	Description
`query`	string	✅	Search query string (e.g. name, email, job title, or keyword).
`limit`	integer	✅	Maximum number of results to return.
`path`	array<string>	✅	One or more searchable field `name` values from the table above (e.g. `fullName`, `position`, `personalInfo.linkedin_url`).
`fuzzy_max_edits`	integer	❌	Maximum edit distance for fuzzy matching (e.g. `2`).

Successful Response (200 OK)

{
  "results": [
    {
      "_id": "string",
      "firstName": "string",
      "lastName": "string",
      "fullName": "string",
      "position": ["string"],
      "investorType": [],
      "personalInfo": {
        "phone": "string"
      },
      "recommended_email": [],
      "emails": [
        {
          "email": "string",
          "smtp_valid": "string",
          "last_validation_check": "string",
          "_id": "string"
        }
      ],
      "recommended_personal_email": [],
      "current_personal_email": [],
      "recommended_professional_email": [
        {
          "email": "string",
          "smtp_valid": "string",
          "last_validation_check": "string",
          "_id": "string"
        }
      ],
      "current_work_email": [],
      "experiences": [],
      "education": []
    }
  ],
  "count": 0
}

Field	Type	Description
`results`	array<object>	Matching people documents returned from Atlas Search.
`count`	integer	Number of results returned.
`results[]._id`	string	MongoDB document identifier for the contact record.
`results[].firstName`	string	Contact’s first name.
`results[].lastName`	string	Contact’s last name.
`results[].fullName`	string	Contact’s full name.
`results[].position`	array<string>	Current job title(s) of the contact.
`results[].investorType`	array	Investor type classifications for the contact.
`results[].personalInfo`	object	Personal details (e.g. `phone`). Additional nested fields may appear based on your `path`.
`results[].recommended_email`	array	Recommended email addresses for the contact.
`results[].emails`	array<object>	Email records with `email`, `smtp_valid`, `last_validation_check`, and `_id`.
`results[].recommended_personal_email`	array	Recommended personal email addresses.
`results[].current_personal_email`	array	Current personal email addresses.
`results[].recommended_professional_email`	array<object>	Recommended professional email records (same shape as `emails` items).
`results[].current_work_email`	array	Current work email addresses.
`results[].experiences`	array<object>	Past work experience records.
`results[].education`	array<object>	Education records.

Validation Error (422)

{
  "status_code": 422,
  "message": "Request validation failed",
  "errors": [
    {
      "field": "body.query",
      "message": "Field required",
      "type": "missing"
    }
  ],
  "data": null
}

Example

curl -X POST "https://chordian-core.chordian.ai/people-search/search" \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "fuzzy_max_edits": 2,
    "limit": 10,
    "path": ["fullName", "personalInfo.linkedin_url"],
    "query": "Jane Smith"
  }'

Company Search APIs Deep Research APIs

People Search APIs

Overview

Start People Search

Request Body

Successful Response (200 OK)

Validation Error (422)

Example

Continue People Search

Request Body

Successful Response (200 OK)

Validation Error (422)

Example

Get People Search Status

Path Parameters

Successful Response (200 OK)

Top-level fields

Criterion (item of criteria[])

TableStructure (table_structure)

Column (item of table_structure.columns[])

Row (item of table_structure.rows[])

Cell (value in Row.cells)

Validation Error (422)

Example

Stop People Search

Path Parameters

Successful Response (200 OK)

Validation Error (422)

Example

Start People Enrichment

Request Body

Successful Response (200 OK)

Validation Error (422)

Example

Stop People Enrichment

Path Parameters

Successful Response (200 OK)

Validation Error (422)

Example

Fetching lists and results (via Company Search)

Get Lists

Successful Response (200 OK)

ListItem (item of data[])

Example

Get Search Result

Path Parameters

Successful Response (200 OK)

Example

Search People

Searchable attributes

Request Body

Successful Response (200 OK)

Validation Error (422)

Example

Criterion (item of `criteria[]`)

TableStructure (`table_structure`)

Column (item of `table_structure.columns[]`)

Row (item of `table_structure.rows[]`)

Cell (value in `Row.cells`)

ListItem (item of `data[]`)