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.
  • full produces the deepest profile.
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 available profiles in their result objects. This is the default.
  • false returns profile IDs, status, generation level, and failures without embedding profile objects.
This setting does not change the work Orbit performs. Results are still built to profile_depth.

​
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. query, intent, or both can be combined with signals. See Structured intent and Start a search for the full schemas.

​
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. v3 Search does not consume credits. Rate limits still apply.