Skip to main content
POST
Creates a saved query for the authenticated organization. The recommended source is the query object returned by GET /people, because it uses the Gateway’s public snake_case filter names. The Gateway compacts the object before storing it: only the allowlisted keys below survive, and null or empty-string values are omitted. This route creates a new record every time. It does not update an existing query, deduplicate by name, or accept an idempotency key.
string
required
Human-readable name, 1–80 characters. The Gateway trims it before storing it. null is not accepted.
object
required
JSON object. The top-level value must be an object and may be empty. Unknown nested keys are silently dropped by compaction; the endpoint does not validate nested search bounds or require a particular filter.
The top-level body accepts only name and query. Nested query values are compacted according to this allowlist: Those bounds are the GET /people request bounds, not POST /queries validation. POST /queries only checks that query is an object; it does not validate nested types, enum values, ranges, or dependencies. A value under an allowlisted key is retained if it is not null or "", even if it would not be accepted by GET /people. To ensure a query is executable, copy it from a successful people-search response and use the search route to validate it. query has no nullable fields in the persisted response: null and empty-string values are removed, while omitted optional keys remain absent. Numeric 0 and boolean false are not removed by compaction, although GET /people would reject values that violate its own bounds.

Response schema

Returns 201 with data:

Errors, side effects, and retry safety

  • 400: missing/invalid name or query, a non-object query, or a missing X-FreshTalent-Org-Id UUID when using the platform API key. The Gateway does not return a nested-field validation error for unknown query keys; it drops them.
  • 401 (unauthorized): provide a valid API key.
  • 402 (payment_required): restore entitlement.
  • 429: back off, but first consider whether the insert already succeeded.
  • 5xx: the outcome can be unknown. This POST is not idempotent; retrying can create duplicate saved queries. Reconcile with List saved queries and compare name plus the persisted compact query before deciding whether to retry.
A saved query is data only; saving it does not execute the search, create a Target, or start monitoring. Its snake_case query can be replayed on people search, but is not directly compatible with Target app_query. See Search query compatibility.

Next steps

Get saved query to retrieve one record, or List saved queries to reconcile a possibly completed POST.