Skip to main content
POST
Creates a standing Target and, when needed, a background discovery job. The operation is asynchronous: creation returns the Target and its current job summary, not the discovered member set.

​
Request body

The body is a JSON object. Only documented fields are supported; the framework strips unknown top-level fields. input is required; the other fields are optional.
​
string
required
1–400 characters before trimming. For company, use a company name, domain, or LinkedIn company URL. For people, use the Target name or fallback search text. For manual, the Target name (the service keeps the first 80 characters). Whitespace-only input passes the JSON length check but is rejected after trimming.
​
string
Exact enum: company, people, or manual. Omitted means company in the service. Do not rely on inference: send the discriminator explicitly.
​
string[]
Required for kind: "manual", ignored otherwise. 1–2000 LinkedIn profile URLs, each at most 500 characters. See kind: "manual".
​
boolean
Default false. With false, discovered members start as proposed; with true, they start as watching. watching members are eligible for enrichment and Monitoring. Changing this later also promotes existing proposed members; it does not promote excluded members.
​
integer
Optional. How many people this Target should discover. Minimum 1. The service clamps the value to the deployment cap (TRACK_COMPANY_MAX_PEOPLE, default 4000). Omit it to use that deployment cap. The dashboard always sends a limit, using remaining monitoring capacity as the ceiling.

​
kind: "company"

A company Target tracks the current company network, including current and alumni discovery performed by the worker. input is provisionally normalized locally, then resolved asynchronously. The company Target is unique per organization and resolved company. If an existing company Target has a latest job in pending, running, or done, this request returns it with 200 and does not enqueue another job. A failed latest job can be re-enqueued. query and app_query are accepted by the route schema but are not used by the company creation service. Omit them.

​
kind: "people"

A people Target runs the stored people query. The service always creates a new people Target and enqueues a track_people job; there is no request idempotency key.
​
object
Optional provider-oriented discovery filters for kind: "people". Supported properties and types are listed below. This is not the echoed graph-search query.
query is the direct Gateway query. Its exact accepted shape is:
All properties are optional. Arrays may be empty; the route declares no per-array item limit. Unknown properties are stripped by the framework. These values are passed into the people discovery query. query.keywords, when present, overrides the generated fallback keyword from input/app_query.
​
object
Optional camelCase app-query object for kind: "people". Use role-object and string arrays as described below; do not paste the snake_case graph-search echo unchanged.
app_query is an object with the following UI query shape. The route validates only that it is an object, so nested types are a service contract rather than a framework validation guarantee:
Every top-level field is optional; each roles item has required family: string, with the other role fields optional. The route declares no nested array length limits. Verified enums are roles[].titleMatch: exact | contains, skillMatch: any | all, and languageMatch: any | all. The mapper uses keywords/school, skills, languages, role titles/families, location/exclusions, and maps a positive companyLeftMinMonthsAgo or betweenRoles: true to recently_changed_jobs: true in the stored Gateway query; the numeric month value itself is not retained there. company may contribute to the UI-derived Target name, but neither company nor companyCurrent is copied into PeopleQuery.company_ids; use verified provider query.company_ids when a company filter is required; the echoed graph-search object is not a substitute. minMonths and scope are accepted role fields but are not mapped into the stored PeopleQuery by this service. Certification is supported by graph people search, but is not supported by people Target discovery. Supplying either app_query.certification or app_query.certifications returns 400 certification_target_unsupported; save and replay the echoed query through Search people when certification matching is required.
Do not pass the echoed snake_case people-search query straight into app_query. The two objects have different types and different meanings. Some fields would be ignored; a string roles value can cause a service error because the mapper expects an array. Do not invent provider company or location IDs.

​
kind: "manual"

A manual Target monitors a fixed set of people you name by LinkedIn profile URL. It never runs discovery, so auto_admit, result_limit, query, and app_query have no effect. The service normalizes each URL to https://www.linkedin.com/in/{slug} (lowercase, except ACoAA… member-id slugs), de-duplicates, and ignores values that are not profile URLs. At least one valid URL is required. Every person starts as watching; there is no proposed step. People already in the graph are ready at once (enriched_count includes them). Everyone else is loaded by a background track_people job that skips discovery; loading can take hours when the queue is busy. Monitoring slots are checked before anything is created: people in the public graph, or already billed to your organization on another Target, are free; everyone else needs one slot. When the request needs more slots than remain, the service returns 409 conflict with a message starting slot_limit: and creates nothing. Use Preview target people to check first, and Add target people to add more later. A manual create always makes a new Target and always returns 202.

​
Search query compatibility

There is no lossless REST conversion from a graph search to a discovery Target: For exact repeat searches, save and replay the query through Search people. For discovery, build the documented Target inputs deliberately and review the returned data.query.filters and members. The MCP has an adapter for echoed queries, but that adapter does not make unsupported provider filters equivalent to graph filters.

​
Response

  • 202 Accepted means a background discovery job was enqueued. A company Target may have been reused rather than newly created.
  • 200 OK means the request reused an existing company Target because its latest job was pending, running, or done.
The body is { "data": Target } with the same Target schema as List targets. job.status is normally pending immediately after enqueue. job.phase starts as queued; later phases may include resolving, discovering, enriching, and done. job.id and job.error are nullable. linkedin_url is nullable until company resolution supplies one and is always null for people Targets.

​
Examples

​
Lifecycle, side effects, and retries

Creation inserts a Target, enqueues discovery, and attempts to create its default list. Discovery and enrichment happen later. Discovery is capped by result_limit when provided, otherwise by TRACK_COMPANY_MAX_PEOPLE (default 4000, configurable at deployment); each saturated provider search leaf is capped at 2500. auto_admit: false leaves new members proposed; setting members to watching is the operation that queues enrichment. A run selects up to 2000 initially unenriched watching members, or up to 500 stale members during refresh, so large Targets may require later work. The worker deduplicates discovered URLs within a Target and uses bounded enrichment retries internally. Discovery usually finishes within 24 hours; the API does not promise a completion time or monitoring freshness. Do not blindly retry a timed-out POST: a people request may already have created a second Target, while a company request may have reused or created a job. First call List targets and reconcile by id, kind, name, and stored query. A 202 is acceptance of the job, not completion.

​
Errors and recovery

  • 400 invalid_request: missing/blank input, invalid kind, invalid top-level type, or invalid JSON schema. Fix the body.
  • 401 unauthorized, 402 payment_required: fix the API key or organization access.
  • 404 not_found: can surface from a service lookup; verify the organization and input.
  • 409 conflict: for kind: "manual", a message starting slot_limit: means the new people need more monitoring slots than remain; nothing was created. Remove some URLs or add capacity. Otherwise the route preserves a service conflict response if one occurs; reconcile before replaying.
  • 429/5xx: back off. For an uncertain write, read the Target collection before retrying rather than replaying blindly.
  • A 202 Target whose job.status later becomes failed is not fixed by polling faster; inspect job.error, then use Retry target after the underlying issue is resolved.

​
Next