openapi: 3.2.0
info:
title: Compensation Benchmarks Dimensions API
license:
name: Apache License, Version 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
version: '1.0'
description: "Discover dimensions and members.\n\nA dimension organizes unique values of an attribute into a list or a hierarchical structure of members. \nThe structure can be navigated to discover the members, and the members can be used to look up benchmark values.\n"
tags:
- name: Dimensions
description: "Discover dimensions and members.\n\nA dimension organizes unique values of an attribute into a list or a hierarchical structure of members. \nThe structure can be navigated to discover the members, and the members can be used to look up benchmark values.\n"
paths:
/v1/compensation-benchmarks/jobs:
get:
summary: Get jobs V1
tags:
- Dimensions
operationId: GetJobsV1
description: 'Retrieve a list of all the jobs in Visier''s ontology. A new version of this endpoint is now available. For more information, see `GET /v2/compensation-benchmarks/jobs`.
'
parameters:
- name: hierarchy
in: query
required: false
schema:
type: string
description: 'The ID of the job hierarchy to navigate.
If not provided, Visier''s default job hierarchy is used. In the default hierarchy, jobs are organized into three levels with domain and subdomain groupings.
'
- name: parent
in: query
required: false
schema:
type: string
description: 'The ID of the parent member.
If the ID is provided, the response returns the immediate children of the parent member.
To get the top-level members, use the value `root`.
Member availability and the parent-child relationship depends on the selected hierarchy. Please refer to the `hierarchy` parameter.
'
- name: term
in: query
required: false
schema:
type: string
description: "The input search term. The job members that are the most semantically similar to the search term are returned with the most relevant job members displayed first. \nYour search term may not be included in the results as semantic search goes beyond keyword matching and attempts to interpret the meaning behind the query to provide search results.\n\nThe minimum length is 2 characters and the maximum length is 100 characters.\n\n***The search term must be URL encoded.***\n"
- name: naicsCode
in: query
required: false
schema:
type: string
description: 'The North American Industry Classification System (NAICS) code.
If `naicsCode` is provided, `term` is required. The most relevant job members associated with the naicsCode are returned first.
'
- name: hasBenchmarkValue
in: query
required: false
schema:
type: boolean
description: "Filter members based on the availability of benchmark values. \nIf `true`, members with benchmark values are returned. \nIf `false`, members without benchmark values are returned. \nIf no value is specified, all members are returned.\n"
- name: semanticOnly
in: query
required: false
schema:
type: boolean
description: 'If `true`, only semantic search will be used to find matches. Ensure the parameter `lexicalOnly` is set to `false`.
Default is `false`. By default, both semantic and lexical search are used to find matches.
'
- name: lexicalOnly
in: query
required: false
schema:
type: boolean
description: "If `true`, only lexical search will be used to find matches. Ensure the parameter `semanticOnly` is set to `false`. \nDefault is `false`. By default, both semantic and lexical search are used to find matches.\n"
- name: typicalTitlesSearch
in: query
required: false
schema:
type: boolean
description: 'If `true`, similar job titles for a job member are included in the lexical search for matches.
Default is `false`.
'
- name: showHierarchy
in: query
required: false
schema:
type: boolean
description: 'If `true`, returns members in a tree structure based on the occupation hierarchy.
Default is `false`.
'
- name: includeArchived
in: query
required: false
schema:
type: boolean
description: 'If `true`, both `active` and `archived` members are returned. Default is `false`. Members are archived when taxonomy changes are made.
'
responses:
'200':
description: 'List of job members.
'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DimensionMember'
'400':
description: 'The API request failed given the parameters provided, such as missing or invalid parameters.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'500':
description: 'An unexpected exception occurred on the server.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'504':
description: 'The server is taking too long to respond and the request timed out.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
x-amazon-apigateway-integration:
type: aws_proxy
credentials: ${apigateway_role}
httpMethod: POST
uri: ${lambda-get-salary-arn}
security:
- api_key: []
/v2/compensation-benchmarks/jobs:
get:
summary: Get jobs V2
tags:
- Dimensions
operationId: GetJobsV2
description: 'Retrieve a list of all the jobs in Visier''s ontology. Jobs V2 improves upon Jobs V1 in the following ways:
- Supports pagination through the `page` and `limit` parameters.
- Returns both the short and long versions of job descriptions and job typical titles.
'
parameters:
- name: hierarchy
in: query
required: false
schema:
type: string
description: 'The ID of the job hierarchy to navigate.
If not provided, Visier''s default job hierarchy is used. In the default hierarchy, jobs are organized into three levels with domain and subdomain groupings.
'
- name: parent
in: query
required: false
schema:
type: string
description: 'The ID of the parent member.
If the ID is provided, the response returns the immediate children of the parent member.
To get the top-level members, use the value `root`.
Member availability and the parent-child relationship depends on the selected hierarchy. Please refer to the `hierarchy` parameter.
'
- name: term
in: query
required: false
schema:
type: string
description: "The input search term. The job members that are the most semantically similar to the search term are returned with the most relevant job members displayed first. \nYour search term may not be included in the results as semantic search goes beyond keyword matching and attempts to interpret the meaning behind the query to provide search results.\n\nThe minimum length is 2 characters and the maximum length is 100 characters.\n\n***The search term must be URL encoded.***\n"
- name: naicsCode
in: query
required: false
schema:
type: string
description: 'The North American Industry Classification System (NAICS) code.
If `naicsCode` is provided, `term` is required. The most relevant job members associated with the naicsCode are returned first.
'
- name: hasBenchmarkValue
in: query
required: false
schema:
type: boolean
description: "Filter members based on the availability of benchmark values. \nIf `true`, members with benchmark values are returned. \nIf `false`, members without benchmark values are returned. \nIf no value is specified, all members are returned.\n"
- name: semanticOnly
in: query
required: false
schema:
type: boolean
description: 'If `true`, only semantic search will be used to find matches. Ensure the parameter `lexicalOnly` is set to `false`.
Default is `false`. By default, both semantic and lexical search are used to find matches.
'
- name: lexicalOnly
in: query
required: false
schema:
type: boolean
description: "If `true`, only lexical search will be used to find matches. Ensure the parameter `semanticOnly` is set to `false`. \nDefault is `false`. By default, both semantic and lexical search are used to find matches.\n"
- name: typicalTitlesSearch
in: query
required: false
schema:
type: boolean
description: 'If `true`, similar job titles for a job member are included in the lexical search for matches.
Default is `false`.
'
- name: showHierarchy
in: query
required: false
schema:
type: boolean
description: 'If `true`, returns members in a tree structure based on the occupation hierarchy.
Default is `false`.
'
- name: includeArchived
in: query
required: false
schema:
type: boolean
description: 'If `true`, both `active` and `archived` members are returned. Default is `false`. Members are archived when taxonomy changes are made.
'
- name: page
in: query
required: false
schema:
type: integer
description: 'The subset of the overall result set to return. The number of rows per page is equal to `limit`, except the last page which may contain fewer rows. Page is an index that begins at 0. The index to start retrieving results is calculated by multiplying `page` by `limit`. Default is to return results for page 0.
'
- name: limit
in: query
required: false
schema:
type: integer
description: 'The maximum number of entries to return. Default and maximum are 1000 entries.
'
responses:
'200':
description: 'List of job members.
'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DimensionMember'
'400':
description: 'The API request failed given the parameters provided, such as missing or invalid parameters.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'500':
description: 'An unexpected exception occurred on the server.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'504':
description: 'The server is taking too long to respond and the request timed out.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
x-amazon-apigateway-integration:
type: aws_proxy
credentials: ${apigateway_role}
httpMethod: POST
uri: ${lambda-get-salary-arn}
security:
- api_key: []
/v1/compensation-benchmarks/jobs/standardize:
post:
summary: Standardize custom job titles in bulk
tags:
- Dimensions
operationId: StandardizeJobsInBulk
description: 'Find the top standardized job matches for any custom job title and optional NAICS code in bulk.
'
requestBody:
description: 'The custom job titles that you want to retrieve standardized jobs for, the optional NAICS code to retrieve industry specific jobs, and the optional number of top matches to retrieve.
By default, both semantic and lexical search are used to find matches. If you want to use a specific search method, set one of the parameters `semanticOnly` or `lexicalOnly` to `true`. Default for `semanticOnly` and `lexicalOnly` are `false`.
The minimum custom job title length is 2 characters and the maximum length is 100 characters. You can submit up to 30 custom job titles per request.
The default number of top matches returned is 5.
'
content:
application/json:
schema:
$ref: '#/components/schemas/JobStandardizationInput'
required: true
responses:
'200':
description: 'The top standardized job matches for each custom job title.
'
content:
application/json:
schema:
$ref: '#/components/schemas/JobStandardizationOutput'
'400':
description: 'The API request failed given the parameters provided, such as missing or invalid parameters.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'500':
description: 'An unexpected exception occurred on the server.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'504':
description: 'The server is taking too long to respond and the request timed out.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
x-amazon-apigateway-integration:
type: aws_proxy
credentials: ${apigateway_role}
httpMethod: POST
uri: ${lambda-get-batch-dimension-members-arn}
security:
- api_key: []
/v1/compensation-benchmarks/jobs/hierarchies:
get:
summary: Get job hierarchies
tags:
- Dimensions
operationId: GetJobHierarchies
description: 'Retrieve a list of all hierarchies used to organize jobs.
'
parameters:
- name: naicsCode
in: query
required: false
schema:
type: string
description: 'The North American Industry Classification System (NAICS) code.
If provided, the response returns the hierarchies associated with the code.
'
responses:
'200':
description: 'List of hierarchies.
'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Hierarchy'
'400':
description: 'The API request failed given the parameters provided, such as missing or invalid parameters.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'500':
description: 'An unexpected exception occurred on the server.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'504':
description: 'The server is taking too long to respond and the request timed out.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
x-amazon-apigateway-integration:
type: aws_proxy
credentials: ${apigateway_role}
httpMethod: POST
uri: ${lambda-get-occupation-hierarchies-arn}
security:
- api_key: []
/v1/compensation-benchmarks/jobs/search:
post:
summary: Search jobs by IDs
tags:
- Dimensions
operationId: SearchJobs
description: 'Retrieve a matching job for each specified job ID.
'
requestBody:
description: 'The job IDs that you want to retrieve a job match.
Include the mandatory `jobIDs` field.
'
content:
application/json:
schema:
$ref: '#/components/schemas/JobSearchInput'
required: true
responses:
'200':
description: "The request was completed. Review the responses individually to see which actions were successful. \nIf you receive a 400 status code for an individual input, it indicates an invalid job ID or no job was found.\n"
content:
application/json:
schema:
$ref: '#/components/schemas/JobSearchOutput'
'400':
description: 'The API request failed due to invalid JSON input, empty input or it exceeded the size limit of 1000 IDs.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'500':
description: 'An unexpected exception occurred on the server.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'504':
description: 'The server is taking too long to respond and the request timed out.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
x-amazon-apigateway-integration:
type: aws_proxy
credentials: ${apigateway_role}
httpMethod: POST
uri: ${lambda-search-jobs-arn}
security:
- api_key: []
/v1/compensation-benchmarks/jobs/feedback:
post:
summary: Send feedback to help improve the quality of the job match results
tags:
- Dimensions
operationId: SubmitJobsFeedback
description: "This API allows you to submit feedback on the quality of the job match results returned by the Get jobs endpoint. \n\nYou must include the search term (job title you entered) in the request body. You can include the optional `naicsCode` if it was used as part of the search in the Get jobs endpoint.\n\nYou can also submit additional comments by providing values for `additionalComments`, along with `term` and `naicsCode`.\n\n**Note:**\n\nFor `term`, the minimum is 2 characters and the maximum is 100 characters.\n\nFor `additionalComments`, the maximum is 750 characters.\n"
requestBody:
description: 'The feedback you want to submit for.
Ensure to include the mandatory fields: search term (`term`).
'
content:
application/json:
schema:
$ref: '#/components/schemas/JobFeedbackInput'
required: true
responses:
'204':
description: 'Your feedback has been submitted successfully.
'
'400':
description: 'Your feedback could not be submitted. Ensure the required fields `term` is not included in the request body.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'500':
description: 'An unexpected exception occurred on the server.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'504':
description: 'The server is taking too long to respond and the request timed out.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
x-amazon-apigateway-integration:
credentials: ${apigateway_role}
httpMethod: POST
uri: ${lambda-submit-match-feedback-arn}
type: aws_proxy
security:
- api_key: []
/v1/compensation-benchmarks/industries:
get:
summary: Get industries
tags:
- Dimensions
operationId: GetIndustries
description: 'Retrieve a list of all available industries.
'
parameters:
- name: parent
in: query
required: false
schema:
type: string
description: 'The ID of the parent member.
If the ID is provided, the response returns the immediate children of the parent member.
To get the top-level members, use the value `root`.
'
- name: naicsCode
in: query
required: false
schema:
type: string
description: 'The North American Industry Classification System (NAICS) code.
If provided, the response returns the best matching member associated with the code.
'
- name: showHierarchy
in: query
required: false
schema:
type: boolean
description: 'If `true`, returns members in a tree structure based on the industry hierarchy.
Default is `false`.
'
- name: hasBenchmarkValue
in: query
required: false
schema:
type: boolean
description: "Filter members based on the availability of benchmark values. \nIf `true`, members with benchmark values are returned. \nIf `false`, members without benchmark values are returned. \nIf no value is specified, all members are returned.\n"
- name: includeArchived
in: query
required: false
schema:
type: boolean
description: 'If `true`, both `active` and `archived` members are returned. Default is `false`. Members are archived when taxonomy changes are made.
'
responses:
'200':
description: 'List of industry members.
'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DimensionMember'
'400':
description: 'The API request failed given the parameters provided, such as missing or invalid parameters.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'500':
description: 'An unexpected exception occurred on the server.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'504':
description: 'The server is taking too long to respond and the request timed out.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
x-amazon-apigateway-integration:
type: aws_proxy
credentials: ${apigateway_role}
httpMethod: POST
uri: ${lambda-get-dimension-members-arn}
security:
- api_key: []
/v1/compensation-benchmarks/locations:
get:
summary: Get locations
tags:
- Dimensions
operationId: GetLocations
description: 'Retrieve a list of all available locations.
'
parameters:
- name: parent
in: query
required: false
schema:
type: string
description: 'The ID of the parent member.
If the ID is provided, the response returns the immediate children of the parent member.
To get the top-level member, use the value `root`.
'
- name: countryCode
in: query
required: false
schema:
type: string
description: 'The **ISO 3166-1** country code to look up. Returns location members that match the country code.
Currently, the only supported country code is `US`.
'
- name: postalCode
in: query
required: false
schema:
type: string
description: 'Postal code to look up. If `postalCode` is provided, `countryCode` is required. Returns location members that match both the country code and postal code.
'
- name: showHierarchy
in: query
required: false
schema:
type: boolean
description: 'If `true`, returns members in a tree structure based on the location hierarchy.
Default is `false`.
'
- name: hasBenchmarkValue
in: query
required: false
schema:
type: boolean
description: "Filter members based on the availability of benchmark values. \nIf `true`, members with benchmark values are returned. \nIf `false`, members without benchmark values are returned. \nIf no value is specified, all members are returned.\n"
- name: includeArchived
in: query
required: false
schema:
type: boolean
description: 'If `true`, both `active` and `archived` members are returned. Default is `false`. Members are archived when taxonomy changes are made.
'
responses:
'200':
description: 'List of location members.
'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DimensionMember'
'400':
description: 'The API request failed given the parameters provided, such as missing or invalid parameters.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'500':
description: 'An unexpected exception occurred on the server.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'504':
description: 'The server is taking too long to respond and the request timed out.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
x-amazon-apigateway-integration:
type: aws_proxy
credentials: ${apigateway_role}
httpMethod: POST
uri: ${lambda-get-dimension-members-arn}
security:
- api_key: []
/v1/compensation-benchmarks/locations/search:
post:
summary: Get location members in bulk
tags:
- Dimensions
operationId: SearchLocationsInBulk
description: 'Retrieve location members in bulk by country code and postal code.
'
requestBody:
description: 'A list of requests that contain a combination of country and postal codes to look up. Returns location members that match both codes.
'
content:
application/json:
schema:
$ref: '#/components/schemas/LocationSearchInput'
required: true
responses:
'200':
description: "The request was completed. Review the responses individually to see which actions were successful. \nIf you receive a 400 status code for an individual input, it indicates an invalid look up code or no location was found.\n"
content:
application/json:
schema:
$ref: '#/components/schemas/LocationSearchOutput'
'400':
description: 'The API request failed due to invalid JSON input, empty input, missing mandatory fields, or it exceeded the bulk size limit of 1000 individual requests.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'500':
description: 'An unexpected exception occurred on the server.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'504':
description: 'The server is taking too long to respond and the request timed out.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
x-amazon-apigateway-integration:
type: aws_proxy
credentials: ${apigateway_role}
httpMethod: POST
uri: ${lambda-get-batch-dimension-members-arn}
security:
- api_key: []
/v1/compensation-benchmarks/company-sizes:
get:
summary: Get company sizes
tags:
- Dimensions
operationId: GetCompanySizes
description: 'Retrieve a list of all available company sizes.
'
parameters:
- name: headcount
in: query
required: false
schema:
type: integer
description: 'The number of employees.
If provided, the response returns the members with the same headcount.
'
- name: hasBenchmarkValue
in: query
required: false
schema:
type: boolean
description: "Filter members based on the availability of benchmark values. \nIf `true`, members with benchmark values are returned. \nIf `false`, members without benchmark values are returned. \nIf no value is specified, all members are returned.\n"
- name: includeArchived
in: query
required: false
schema:
type: boolean
description: 'If `true`, both `active` and `archived` members are returned. Default is `false`. Members are archived when taxonomy changes are made.
'
responses:
'200':
description: 'List of company size members.
'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DimensionMember'
'400':
description: 'The API request failed given the parameters provided, such as missing or invalid parameters.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'500':
description: 'An unexpected exception occurred on the server.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'504':
description: 'The server is taking too long to respond and the request timed out.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
x-amazon-apigateway-integration:
type: aws_proxy
credentials: ${apigateway_role}
httpMethod: POST
uri: ${lambda-get-dimension-members-arn}
security:
- api_key: []
/v1/compensation-benchmarks/career-levels:
get:
summary: Get career levels
tags:
- Dimensions
operationId: GetCareerLevels
description: 'Retrieve a list of all available career levels.
'
parameters:
- name: job
in: query
required: false
schema:
type: string
description: 'The job member ID.
If provided, the response returns the members for the job.
'
- name: hasBenchmarkValue
in: query
required: false
schema:
type: boolean
description: "Filter members based on the availability of benchmark values. \nIf `true`, members with benchmark values are returned. \nIf `false`, members without benchmark values are returned. \nIf no value is specified, all members are returned.\n"
- name: includeArchived
in: query
required: false
schema:
type: boolean
description: 'If `true`, both `active` and `archived` members are returned. Default is `false`. Members are archived when taxonomy changes are made.
'
responses:
'200':
description: 'List of career level members.
'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DimensionMember'
'400':
description: 'The API request failed given the parameters provided, such as missing or invalid parameters.
'
content:
application/json:
schema:
# --- truncated at 32 KB (53 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/visier/refs/heads/main/openapi/visier-dimensions-api-openapi.yml