Visier Compensation Benchmarks API

openapi: "3.0.1"
info:
  title: Compensation Benchmarks API
  license:
    name: Apache License, Version 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: "1.0"
tags:
  - name: Benchmarks
    description: |
      Get benchmark values.
  - 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/base-salary:
    get:
      summary: Get base salary benchmark value
      tags: [Benchmarks]
      operationId: GetSalaryBenchmark
      description: |
        Retrieve the base salary benchmark value.
      parameters:
        - name: job
          in: query
          required: true
          schema:
            type: string
          description: |
            The job member ID.
        - name: industry
          in: query
          required: false
          schema:
            type: string
          description: |
            The industry member ID. If the ID is not provided, the response returns the benchmark value across all industries.
        - name: naicsCode
          in: query
          required: false
          schema:
            type: string
          description: "The North American Industry Classification System (NAICS) code. \n\nIf the NAICS code is not provided, the response returns the benchmark value across all industries.\nIf both `naicsCode` and `industry` are provided, the response returns the benchmark value for the `industry` parameter. The entered `naicsCode` will not be applied.\n"
        - name: location
          in: query
          required: false
          schema:
            type: string
          description: |
            The location member ID. If the ID is not provided, the response returns the benchmark value across all locations.
        - name: companySize
          in: query
          required: false
          schema:
            type: string
          description: |
            The company size member ID. If the ID is not provided, the response returns the benchmark value across all company sizes.
        - name: careerLevel
          in: query
          required: false
          schema:
            type: string
          description: |
            The career level member ID. If the ID is not provided, the response returns the benchmark value across all career levels.
        - name: matchDate
          in: query
          required: false
          schema:
            type: string
          description: |
            The date on which the career level was matched in `yyyy-MM-dd` format. A `matchDate` allows precise migration of career levels according to job architecture changes released since the match was made. If `matchDate` is not available, the migration assumes the most recent possible match date for the provided career level.
      responses:
        "200":
          description: |
            The requested base salary benchmark value.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BenchmarkValue"
        "400":
          description: |
            The API request failed given the parameters provided, such as missing parameters, invalid parameters, or there is no benchmark value available.
          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/base-salary/feedback:
    post:
      summary: Submit feedback to improve salary benchmark values
      tags: [Benchmarks]
      operationId: "SubmitSalaryBenchmarkFeedback"
      description: |
        Give feedback for a salary benchmark value returned by `GET /v1/compensation-benchmarks/base-salary` or `/base-salaries`. To submit feedback, include the benchmark value's:
          * ID values you defined in `GET /v1/compensation-benchmarks/base-salary` or `/base-salaries`.
          * `referenceDate` and `releaseDate` returned by `GET /v1/compensation-benchmarks/base-salary` or `/base-salaries`.
          * Optional `additionalComments` up to 750 characters.
      requestBody:
        description: |
          The feedback to submit.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SalaryBenchmarkFeedbackInput"
        required: true
      responses:
        "204":
          description: |
            Your feedback has been submitted successfully.
        "400":
          description: |
            Your feedback could not be submitted. Ensure all mandatory fields are 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-benchmark-feedback-arn}"
        type: "aws_proxy"
      security:
        - api_key: []
  /v1/compensation-benchmarks/base-salaries:
    post:
      summary: Get salary benchmark values in bulk
      tags: [Benchmarks]
      operationId: "GetSalaryBenchmarksInBulk"
      description: |
        Retrieve multiple base salary benchmark values in a single request.
      requestBody:
        description: |
          A batch request takes a JSON object consisting of an array of your requests. You can batch up to 1000 individual requests in one API call.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SalaryBenchmarkInputs"
        required: true
      responses:
        "200":
          description: "The bulk request was completed. Review the responses individually to see which actions were successful. \nIf you receive a 400 status code for an individual response, it indicates missing parameters, invalid members, or no benchmark values were found.\n"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SalaryBenchmarksBatchProcessingOutputs"
        "400":
          description: |
            The API request failed due to invalid JSON input, empty input 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-benchmarks-arn}"
      security:
        - api_key: []
  /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
     

# --- truncated at 32 KB (72 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/visier/refs/heads/main/openapi/visier-compensation-benchmarks-openapi.yaml