Skip to main content
Search turns a plain-English query, structured criteria, or identity signals into a set of useful people profiles. Every request makes three independent choices.

​
1. Candidate Discovery

candidate_discovery controls where Orbit looks:
  • false searches people Orbit already knows. This is the default.
  • true returns known matches and continues finding additional people when the input supports discovery.
With candidate_discovery: true, address, email, and phone signals can return multiple associated people. Orbit keeps each unique person as a separate result and builds every result to the requested profile depth. candidate_discovery_limit defaults to 10 and can be set from 1–50. A lower value reduces downstream profile-generation fanout, although source discovery and clustering can still dominate initial discovery time.

​
2. Profile Depth

profile_depth controls how far Orbit builds every selected result:
  • partial produces a useful partial profile and is the default. A search whose results need only partial-depth builds completes in under two minutes.
  • full produces the deepest profile. Each full-depth build takes 25 to 30 minutes.
Search does not return level 1 profiles as ready results. A result stays enriching until it reaches the requested depth, or becomes failed if the profile cannot be built.

​
3. Profile Embedding

include_profile controls response shape:
  • true embeds each readable result’s profile with its identity and contact fields and its generated sections, such as bio, jobs, and education. This is the default.
  • false returns profile IDs, status, generation level, and failures without embedding profile objects.
This setting controls response shape only. Orbit builds every result to profile_depth with either value, and generation_level reports how deep each embedded profile is. For a profile’s image gallery and source links, call Read a profile.

​
Inputs

Use query for a normal plain-English search. Orbit routes the query and, when candidate discovery is enabled, derives structured intent for the discovery phase:
Use intent alone when your application already has fully structured criteria:
You can also send query and intent together when plain English provides useful context but exact structured fields must take precedence:
Orbit derives a base intent from query and then overlays your intent. At each supplied field, arrays, scalar values, and null replace the derived value; nested objects merge field by field. Known-profile Search uses the original query plus the merged intent. Candidate Discovery uses the merged intent. Use signals for facts that may identify a specific person:
An address, email, or phone number may belong to more than one person. Candidate Discovery returns every unique match up to candidate_discovery_limit. signals.face_source searches by a face from a photo. See Face Search. query, intent, or both can be combined with signals. See Structured intent and Start a search for the full schemas.

​
Populations

A plain-English query about one company or one school and no particular person (“engineers at OpenAI”, “people who went to Stanford”) can be answered as a whole: every current employee of the company, or everyone who attended the school. The snapshot’s query_intent reports the organizations and schools a query names and whether it names a person, so you can offer that when it fits. Price a population to see the cost, then search it. People are added to the results as the search finds them, at the profile_depth you chose. Face search finds the people a photo could show. It returns a list of possible people, best match first, each with a confidence score.
  1. Find the faces. Send the photo to Detect faces. Orbit stores the photo privately and returns its image_url reference and every face in it, each with a bbox.
  2. Pick a face. Let your user choose the face. The next steps take the photo’s image_url and the face’s bbox.
  3. Check known profiles (optional). Search the face index returns the Orbit profiles that already show the face. It is free and answers at once.
  4. Search for the face. Start a search with the face in signals.face_source:
Orbit searches the web for the face, checks every page it finds with its face model, and groups the matching pages by person. Each group becomes a result, up to candidate_discovery_limit (default 10). Poll the search like any other. Each result carries confidence, confidence_level, and confidence_status. They include how strongly the face matches that person: how close the best match is, and how many pages confirm it. Results come best match first. none_of_above_confidence is one minus the best result’s confidence: it is high when no result matches well. Each page the search found a face on carries face_match with the page’s score, whether it is confirmed, and whether the search kept it. A page with kept true is a page of the picked face, and a confirmed page is a strong match. A page with kept false shows another face that looks alike. Pages appear in discovered_sources as the search finds them, so you can show them while the search runs. Each result’s pages are in its candidate_sources. Results are the people that pages of the picked face show. Faces that look alike stay in discovered_sources with kept false. List them as other faces. A name or other context helps. Add a query such as the person’s name, or other signals, and Orbit ranks a result whose details match it higher. The face still decides who is in the list. When the face pages name nobody, the search ends with candidate_discovery_failure code face_not_named, and discovered_sources holds the pages that show the face. When the picked face is unreadable, the code is face_unusable: pick a clearer face and search again. The picked face becomes each result’s reference face: profile photos come from the images that match it. The photo stays private to your request, and Orbit keeps it for 7 days. A face search costs the face search rate when Orbit searches the web for the face, plus the normal profile rate for each person returned. See API credits.

​
Lifecycle

POST /v3/search returns one Search resource. The response may already contain ready results while other work continues. Poll GET /v3/search/{search_id} while the resource is running. completed_with_errors is usable partial success: preserve ready results and inspect failures individually.

​
Idempotency

Set request_id to a stable identifier that your application persists before the first POST. Retrying the same logical request with the same ID returns the existing Search. Reusing it with different inputs returns 409. The ID belongs to your API key, so when one key serves many users, add a per-user prefix. Search uses API credits for the work requested and profiles returned. Rate limits also apply.