Jobs Search reference - Crustdata Docs

Reference material for Search Jobs: common indexed fields, the full Job catalog, id semantics, aggregation bucket metadata, null behavior, and errors. For filter grammar and example queries, see Filters & recipes. For sorting, pagination, field selection, and aggregations, see Pagination & sorting.

Jobs ID cheat sheet. The Jobs APIs use three id concepts — keep them straight:

crustdata_job_id — the Crustdata job identifier. Returned on every Job. Use it as your dedupe key.
company.basic_info.crustdata_company_id — the Crustdata company identifier returned on every Job.
company.basic_info.company_id (filter alias) — the dot-path used in filters and aggregations.column for indexed Search Jobs. It points to the same integer as company.basic_info.crustdata_company_id. This alias is not sortable; for deterministic pagination, sort on metadata.date_added instead.

When you group_by on company.basic_info.company_id, each bucket also returns metadata.company_name, metadata.company_website_domain, and metadata.linkedin_id for labeling.

Common indexed fields

These are the indexed fields most often used in filters, sorts, and aggregations.column. This table is a summary of the most common paths, not an authoritative catalog. For the deeper field catalog — including id semantics, null handling, and bucket metadata — see the full Field reference below.

Company id filter alias. The filterable field path uses the short alias company.basic_info.company_id, but the response shape returns the same integer at company.basic_info.crustdata_company_id. They point to the same value. See Jobs IDs: a quick map.

Job details
Company basic info
Company firmographics
Location
Content, metadata, IDs

Field	Example
`job_details.title`	`"Software Engineer"`
`job_details.category`	`"Engineering"`, `"Sales"`, `"Operations"`, `"Others"`
`job_details.workplace_type`	`"Remote"`, `"Hybrid"`, `"On-site"`, `""`
`job_details.reposted_job`	`true` / `false`
`job_details.url`	`"https://www.linkedin.com/jobs/view/4398377738"`

Field	Example
`company.basic_info.company_id`	`631394`
`company.basic_info.name`	`"Stripe"`
`company.basic_info.primary_domain`	`"stripe.com"`
`company.basic_info.professional_network_id`	`"2135371"`
`company.basic_info.industries`	`["Technology, Information and Internet"]`

Field	Example
`company.headcount.total`	`14522`
`company.headcount.range`	`"5001-10000"`
`company.followers.count`	`1335688`
`company.revenue.estimated.lower_bound_usd`	`500000000`

Field	Example
`location.raw`	`"Melbourne, Victoria, Australia"`
`location.country`	`"Australia"`
`location.state`	`"Victoria"`
`location.district`	`"Southbank"`
`location.city`	`"Melbourne"`

Field	Example
`content.description`	Full job description text.
`crustdata_job_id`	`41053563`
`metadata.date_added`	`"2026-04-07T11:37:29"`
`metadata.date_updated`	`"2026-04-08T00:00:00"`

Sending a filter on a non-indexed field returns 400 with Unsupported columns in conditions: ['...']. Sending an unsupported group_by column returns a similar error listing every supported aggregation column.

Field reference

This section covers the return shape, id semantics, aggregation bucket metadata, and the most important indexed field catalogs in one place.

Annotated full `Job` example

The code fence below uses jsonc because it includes inline // comments for annotation. Strip the comments before sending it to a strict JSON parser.

{
    "crustdata_job_id": 41053563, // stable job id (use as dedupe key)
    "job_details": {
        "job_id": 41053563, // mirrors crustdata_job_id
        "title": "Integration Engineer (AUNZ)",
        "category": "Engineering",
        "workplace_type": "",
        "url": "https://www.linkedin.com/jobs/view/4398377738",
        "reposted_job": false,
        "number_of_openings": 1,
    },
    "company": {
        "basic_info": {
            "crustdata_company_id": 631394, // filter with company.basic_info.company_id
            "name": "Stripe",
            "primary_domain": "stripe.com",
            "website": "https://stripe.com",
            "professional_network_id": "2135371",
            "industries": ["Technology, Information and Internet"],
        },
        "locations": {
            "country": "USA",
            "state": "California",
            "city": "South San Francisco",
            "street_address": "354 Oyster Point Blvd, South San Francisco, California, United States",
        },
        "headcount": {
            "total": 7234,
            "range": "5001-10000",
            "largest_headcount_country": "USA",
        },
        "followers": { "count": 1335688 },
        "revenue": {
            "estimated": {
                "lower_bound_usd": 500000000,
                "upper_bound_usd": 1000000000,
            },
            "public_markets": null,
            "acquisition_status": "",
        },
        "funding": {
            "total_investment_usd": 9440247725.0,
            "valuation_usd": 50000000000.0,
            "last_fundraise_date": "2026-03-09T00:00:00",
            "last_round_type": "secondary_market",
            "num_funding_rounds": 23,
            "investors": [
                "Sequoia Capital",
                "Andreessen Horowitz",
                "Founders Fund",
            ],
        },
        "competitors": {
            "websites": ["https://plaid.com", "https://paystack.com"],
        },
    },
    "location": {
        "raw": "Melbourne, Victoria, Australia",
        "city": "Melbourne",
        "district": null,
        "state": "Victoria",
        "country": "Australia",
        "pincode": null,
    },
    "content": {
        "description": "Stripe is a financial infrastructure platform for businesses...",
    },
    "metadata": {
        "date_added": "2026-04-07T11:37:29",
        "date_updated": "2026-04-08T00:00:00",
    },
}

Nulls are normal. Nested objects such as revenue.public_markets, location.district, location.pincode, and parts of company.funding can legitimately be null or missing.

Jobs IDs: a quick map

ID	Lives on	Purpose
`crustdata_job_id`	Top-level on each `Job`	Crustdata job identifier. Use it as your dedupe key in your own store.
`job_details.job_id`	Inside `Job.job_details`	Secondary job identifier. It currently mirrors `crustdata_job_id` and is kept for backwards compatibility.
`company.basic_info.crustdata_company_id`	Inside `Job.company.basic_info`	Crustdata company identifier returned on each row.
`company.basic_info.company_id`	Search filter / aggregation path	Indexed alias for the same company identifier. Use this in `filters.field` and `aggregations.column`.

Aggregation bucket metadata

When you group_by on company.basic_info.company_id, each bucket carries a metadata object whose keys use bucket-specific names rather than the Job response dot-paths:

Bucket metadata key	Equivalent `Job` value	Notes
`company_name`	`company.basic_info.name`	Plain company name.
`company_website_domain`	`company.basic_info.primary_domain`	Primary website domain.
`linkedin_id`	`company.basic_info.professional_network_id`	Public-profile identifier returned only inside aggregation buckets.
`crustdata_company_id`	`company.basic_info.crustdata_company_id`	Crustdata company id. Defined in the spec as nullable; the bucket `key` already carries this value.

Job identifiers

Path	Type	Filter	Sort	Group	Return	Example
`crustdata_job_id`	integer	✅	—	—	✅	`41053563`
`job_details.job_id`	integer	—	—	—	✅	`41053563`

Job details (`job_details.*`)

Path	Type	Filter	Sort	Group	Return	Example
`job_details.title`	string	✅	—	✅	✅	`"Software Engineer"`
`job_details.category`	string	✅	—	✅	✅	`"Engineering"`
`job_details.workplace_type`	string	✅	—	✅	✅	`"Remote"`, `"Hybrid"`, `"On-site"`, `""`
`job_details.reposted_job`	boolean	✅	—	—	✅	`false`
`job_details.url`	string	✅	—	—	✅	`"https://www.linkedin.com/jobs/view/4398377738"`
`job_details.number_of_openings`	integer	—	—	—	✅	`1`

Company basic info (`company.basic_info.*`)

Path	Type	Filter	Sort	Group	Return	Example
`company.basic_info.company_id`	integer	✅	—	✅	—	`631394`
`company.basic_info.crustdata_company_id`	integer	—	—	—	✅	`631394`
`company.basic_info.name`	string	✅	—	—	✅	`"Stripe"`
`company.basic_info.primary_domain`	string	✅	—	✅	✅	`"stripe.com"`
`company.basic_info.website`	string	—	—	—	✅	`"https://stripe.com"`
`company.basic_info.professional_network_id`	string	✅	—	—	✅	`"2135371"`
`company.basic_info.industries`	string[]	✅	—	✅	✅	`["Technology, Information and Internet"]`

company.basic_info.company_id and company.basic_info.crustdata_company_id refer to the same integer. Use the short alias in filters and aggregations.column. The response shape writes the value under crustdata_company_id.

Company firmographics

Headcount (`company.headcount.*`)

Path	Type	Filter	Sort	Group	Return	Example
`company.headcount.total`	integer	✅	✅	—	✅	`14522`
`company.headcount.range`	string	✅	—	✅	✅	`"5001-10000"`
`company.headcount.largest_headcount_country`	string	—	—	—	✅	`"USA"`

Followers (`company.followers.*`)

Path	Type	Filter	Sort	Group	Return	Example
`company.followers.count`	integer	✅	✅	—	✅	`1335688`

Revenue (`company.revenue.*`)

Path	Type	Filter	Sort	Group	Return	Example
`company.revenue.estimated.lower_bound_usd`	integer	✅	✅	—	✅	`500000000`
`company.revenue.estimated.upper_bound_usd`	integer	✅	✅	—	✅	`1000000000`
`company.revenue.acquisition_status`	string	✅	—	—	✅	`""`
`company.revenue.public_markets.stock_symbols`	string[]	—	—	—	✅	`["STRIPE"]`
`company.revenue.public_markets.fiscal_year_end`	string	—	—	—	✅	`""`

Funding (`company.funding.*`)

Path	Type	Filter	Sort	Group	Return	Example
`company.funding.total_investment_usd`	number	✅	✅	—	✅	`9440247725.0`
`company.funding.valuation_usd`	number	✅	✅	—	✅	`50000000000.0`
`company.funding.last_fundraise_date`	string (ISO 8601)	✅	✅	—	✅	`"2026-03-09T00:00:00"`
`company.funding.last_round_type`	string	✅	—	✅	✅	`"secondary_market"`
`company.funding.num_funding_rounds`	integer	✅	✅	—	✅	`23`
`company.funding.investors`	string[]	—	—	—	✅	`["Sequoia Capital"]`

Competitors and company locations

Path	Type	Filter	Sort	Group	Return	Example
`company.competitors.websites`	string[]	—	—	—	✅	`["https://plaid.com"]`
`company.locations.country`	string	✅	—	✅	✅	`"USA"`
`company.locations.state`	string	—	—	—	✅	`"California"`
`company.locations.city`	string	—	—	—	✅	`"South San Francisco"`
`company.locations.street_address`	string	—	—	—	✅	`"354 Oyster Point Blvd, ..."`

Job location (`location.*`)

Path	Type	Filter	Sort	Group	Return	Example
`location.raw`	string	✅	—	—	✅	`"Melbourne, Victoria, Australia"`
`location.city`	string	✅	—	—	✅	`"Melbourne"`
`location.district`	string	✅	—	—	✅	`"Southbank"`
`location.state`	string	✅	—	—	✅	`"Victoria"`
`location.country`	string	✅	—	✅	✅	`"Australia"`
`location.pincode`	string	✅	—	—	✅	`"3006"`

Country value normalization. location.country can appear as full names ("United States"), ISO-style short forms ("USA"), and occasional variants ("United States of America"). When filtering by country, either match multiple variants with in or pre-discover the exact indexed values by running a group_by on location.country.

Content (`content.*`)

Path	Type	Filter	Sort	Group	Return	Example
`content.description`	string	✅	—	—	✅	`"Stripe is a financial infrastructure..."`

Use the (.) operator on content.description to find listings by technology, skill, or keyword.

Metadata (`metadata.*`)

Path	Type	Filter	Sort	Group	Return	Example
`metadata.date_added`	string (ISO 8601)	✅	✅	—	✅	`"2026-04-07T11:37:29"`
`metadata.date_updated`	string (ISO 8601)	✅	✅	—	✅	`"2026-04-08T00:00:00"`

Null, blank, and sparse field behavior

Most Job fields are nullable in the spec and can legitimately be absent or empty.

Null or missing — the field is not present on a given Job.
Blank string "" — the field was present but had no indexable value (common for job_details.workplace_type). Treat blank as “unspecified”, not as the same thing as null.
Sparse nested objects — company.funding, company.revenue, and company.competitors are often missing for smaller or private companies.
is_null / is_not_null operators are currently not implemented — request the field via fields and filter for null presence client-side.

Errors

Status	Envelope shape	Meaning
`400`	`{ "error": { "type", "message", "metadata" } }`	Invalid request — unsupported filter column, unsupported aggregation column, `limit` out of range, or malformed body. `error.type` is `invalid_request` for validation failures and `internal_error` for unsupported-column checks.
`401`	`{ "message": "..." }` (flat — not the `error` envelope)	Unauthorized — the `Authorization` header is missing, malformed, or contains an invalid API key.
`500`	`{ "error": { "type", "message", "metadata" } }`	Internal server error — retry after a short delay.

401 uses a different response shape than 400/500. Parse the response based on HTTP status: 401 is a flat { "message": ... }, every other 4xx/5xx is the nested { "error": { "type", "message", "metadata" } } envelope.

{
    "error": {
        "type": "internal_error",
        "message": "Unsupported columns in conditions: ['invalid_field']",
        "metadata": []
    }
}

What’s next

Search Jobs — back to the main Search page.
Filters & recipes — filter grammar, operators, and example queries.
Pagination & sorting — sorting, pagination, field selection, and aggregations.
OpenAPI reference — the formal schema for every request, response, and error.

Documentation Index

​Common indexed fields

​Field reference

​Annotated full Job example

​Jobs IDs: a quick map

​Aggregation bucket metadata

​Job identifiers

​Job details (job_details.*)

​Company basic info (company.basic_info.*)

​Company firmographics

​Headcount (company.headcount.*)

​Followers (company.followers.*)

​Revenue (company.revenue.*)

​Funding (company.funding.*)

​Competitors and company locations

​Job location (location.*)

​Content (content.*)

​Metadata (metadata.*)

​Null, blank, and sparse field behavior

​Errors

​What’s next

Common indexed fields

Field reference

Annotated full `Job` example

Jobs IDs: a quick map

Aggregation bucket metadata

Job identifiers

Job details (`job_details.*`)

Company basic info (`company.basic_info.*`)

Company firmographics

Headcount (`company.headcount.*`)

Followers (`company.followers.*`)

Revenue (`company.revenue.*`)

Funding (`company.funding.*`)

Competitors and company locations

Job location (`location.*`)

Content (`content.*`)

Metadata (`metadata.*`)

Null, blank, and sparse field behavior

Errors

What’s next