Search job postings - Autotouch AI

This page documents the canonical HTTP contract for this endpoint.

The request uses the public JobsSearchRequest semantic fields. Provider selection and provider paging remain host-owned. The HTTP model also accepts resolved_hiring_locations and resolved_industries as internal resolved-value overrides; if supplied, they affect provider compilation and take precedence over the corresponding hiring_locations or industries values. Omit them in ordinary requests. The returned result metadata and pricing_rule describe the executed search.

Use credits_used and pricing_rule returned by the API for the effective charge.

The common response envelope contains items, total_found, billable_results, credits_used, pricing_rule, and metadata. Result item fields depend on this search family.

Body parameters

query · optional
string
Optional natural-language job-search anchor.
job_titles · optional
array<string>
Job titles in postings, not buyer/persona titles.
keywords · optional
array<string>
Terms for the posting or description.
hiring_locations · optional
array<string>
Job-posting locations, distinct from company headquarters.
resolved_hiring_locations · optional
array<string>
Internal resolved-location override accepted by the HTTP model. When supplied, it takes precedence over hiring_locations during provider compilation; omit it in ordinary requests.
company_locations · optional
array<string>
Company or headquarters locations.
company_names · optional
array<string>
Companies to include when named by the caller.
company_exclusions · optional
array<string>
Companies to exclude.
company_domains · optional
array<string>
Company domains to include.
industries · optional
array<string>
Hiring-company industries.
resolved_industries · optional
array<string>
Internal resolved-industry override accepted by the HTTP model. When supplied, it takes precedence over industries for provider compilation; omit it in ordinary requests.
company_sizes · optional
array<string>
Hiring-company size ranges.
lookback_window · optional
string
One of 1h, 24h, 7d, or 6m; default 24h.
remote_only · optional
boolean
Keep only provider-marked remote postings; default false.
include_beta · optional
boolean
Optional source-output choice for Fantastic Jobs beta fields.
title_expansions · optional
array<JobsTitleExpansion>
Optional title groups with source_title, canonical_title, aliases, and exclude_titles.
result_policy · optional
JobsResultPolicy
Optional deterministic policy for company location/size and hiring-country filtering.
limit · optional
integer
Maximum normalized results; default 25, range 1–100.

Name	Type	Description
query	string	Optional natural-language job-search anchor.
job_titles	array<string>	Job titles in postings, not buyer/persona titles.
keywords	array<string>	Terms for the posting or description.
hiring_locations	array<string>	Job-posting locations, distinct from company headquarters.
resolved_hiring_locations	array<string>	Internal resolved-location override accepted by the HTTP model. When supplied, it takes precedence over hiring_locations during provider compilation; omit it in ordinary requests.
company_locations	array<string>	Company or headquarters locations.
company_names	array<string>	Companies to include when named by the caller.
company_exclusions	array<string>	Companies to exclude.
company_domains	array<string>	Company domains to include.
industries	array<string>	Hiring-company industries.
resolved_industries	array<string>	Internal resolved-industry override accepted by the HTTP model. When supplied, it takes precedence over industries for provider compilation; omit it in ordinary requests.
company_sizes	array<string>	Hiring-company size ranges.
lookback_window	string	One of 1h, 24h, 7d, or 6m; default 24h.
remote_only	boolean	Keep only provider-marked remote postings; default false.
include_beta	boolean	Optional source-output choice for Fantastic Jobs beta fields.
title_expansions	array<JobsTitleExpansion>	Optional title groups with source_title, canonical_title, aliases, and exclude_titles.
result_policy	JobsResultPolicy	Optional deterministic policy for company location/size and hiring-country filtering.
limit	integer	Maximum normalized results; default 25, range 1–100.

Definitions

JobsTitleExpansion

Optional title expansion group; extra fields are rejected.

Fields

source_titlerequired
string
Original title to expand; sourceTitle alias is also accepted.
canonical_title · optional
string
Canonical title; defaults to an empty string. canonicalTitle alias is also accepted.
aliases · optional
array<string>
Additional title variants; defaults to an empty array.
exclude_titles · optional
array<string>
Titles to exclude; defaults to an empty array. excludeTitles alias is also accepted.

Name	Type	Description
source_titlerequired	string	Original title to expand; sourceTitle alias is also accepted.
canonical_title	string	Canonical title; defaults to an empty string. canonicalTitle alias is also accepted.
aliases	array<string>	Additional title variants; defaults to an empty array.
exclude_titles	array<string>	Titles to exclude; defaults to an empty array. excludeTitles alias is also accepted.

JobsResultPolicy

Optional policy applied after provider normalization; extra fields are rejected.

Fields

company_location · optional
string
hard_match, soft_match_if_ambiguous, or off. Default: soft_match_if_ambiguous.
company_size · optional
string
hard_match_when_present, soft_match, or off. Default: hard_match_when_present.
hiring_country · optional
string
provider_only or hard_match. Default: provider_only.
hiring_country_relation · optional
string
off or different_from_company_hq. Default: off.

Name	Type	Description
company_location	string	hard_match, soft_match_if_ambiguous, or off. Default: soft_match_if_ambiguous.
company_size	string	hard_match_when_present, soft_match, or off. Default: hard_match_when_present.
hiring_country	string	provider_only or hard_match. Default: provider_only.
hiring_country_relation	string	off or different_from_company_hq. Default: off.

Errors

Status	Meaning
400	The search command or provider rejected the request.
401	Authentication is required.
402	Insufficient credits for this search.
403	Developer API key lacks required scope: search:run.
422	A request field is missing, outside its allowed range, or fails the typed request contract.

Example

bash

curl -X POST "https://app.autotouch.ai/api/search/jobs" -H "Authorization: Bearer $AUTOTOUCH_API_KEY" -H "Content-Type: application/json" -d '{"job_titles":["Account Executive"],"hiring_locations":["New York, NY"],"lookback_window":"7d","limit":25}'

Request body

json

{
  "job_titles": [
    "Account Executive"
  ],
  "hiring_locations": [
    "New York, NY"
  ],
  "lookback_window": "7d",
  "limit": 25
}

Response example

json

{
  "items": [],
  "total_found": 0,
  "billable_results": 0,
  "credits_used": 0,
  "pricing_rule": "<effective rule for this search>",
  "metadata": {}
}