openapi: 3.0.3
info:
  title: JAGGAER ASO Customer Host Entity Service Async Events API
  description: 'The Customer Host Entity Service (CHES) API provides system-to-system REST endpoints for managing customer hosts, users, events, and templates within the JAGGAER Advanced Sourcing Optimizer (ASO) platform. It enables creation and retrieval of sourcing events, template management, user administration, and location-based rate structure queries using OAuth 2.0 bearer tokens combined with API key authentication.

    '
  version: v26.0.0.4
  contact:
    name: JAGGAER Support
    url: https://www.jaggaer.com/support
  x-api-id: jaggaer-aso-ches
servers:
- url: https://ches.aso-api.jaggaer.com
  description: JAGGAER ASO CHES Production Server
security:
- bearerAuth: []
  apiKeyHeader: []
tags:
- name: Events
  description: Sourcing event operations
paths:
  /chost/{customer-host-id}/user/{user-id}/template/{template-id}/apiEvent:
    post:
      operationId: createEventFromTemplate
      summary: Event from Template by User
      description: 'Creates a new sourcing event synchronously from the specified template for the given user under the customer host. Returns the created event details upon success.

        '
      tags:
      - Events
      parameters:
      - $ref: '#/components/parameters/customerHostId'
      - $ref: '#/components/parameters/userId'
      - $ref: '#/components/parameters/templateId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventCreateRequest'
      responses:
        '200':
          description: Success; event created from template.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /chost/{customer-host-id}/user/{user-id}/template/{template-id}/apiEvent/async:
    post:
      operationId: createEventFromTemplateAsync
      summary: Event from Template by User (Asynchronous)
      description: 'Initiates an asynchronous creation of a sourcing event from the specified template for the given user. Returns a process ID that can be used to poll /asyncStatus/{encoded-async-pid} for completion.

        '
      tags:
      - Events
      parameters:
      - $ref: '#/components/parameters/customerHostId'
      - $ref: '#/components/parameters/userId'
      - $ref: '#/components/parameters/templateId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventCreateRequest'
      responses:
        '202':
          description: 'Accepted; returns an encoded async process ID for polling via /asyncStatus/{encoded-async-pid}.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncAcceptedResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /chost/{customer-host-id}/user/{user-id}/apiEvents:
    get:
      operationId: getEventsByUser
      summary: Events by User
      description: 'Retrieves all sourcing events accessible to the specified user under the given customer host.

        '
      tags:
      - Events
      parameters:
      - $ref: '#/components/parameters/customerHostId'
      - $ref: '#/components/parameters/userId'
      responses:
        '200':
          description: Success; returns a list of events for the user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    templateId:
      name: template-id
      in: path
      required: true
      description: Identifier for the sourcing event template.
      schema:
        type: integer
    customerHostId:
      name: customer-host-id
      in: path
      required: true
      description: Identifier for the customer host in the ASO platform.
      schema:
        type: integer
    userId:
      name: user-id
      in: path
      required: true
      description: Identifier for the user.
      schema:
        type: integer
  schemas:
    EventCreateRequest:
      type: object
      description: Request body for creating a sourcing event from a template.
      properties:
        eventName:
          type: string
          description: Name for the new sourcing event. (Max length 100)
          maxLength: 100
        eventDescription:
          type: string
          description: Optional description for the event.
    ErrorResponse:
      type: object
      description: Error response with validation details.
      properties:
        statuses:
          type: object
          description: Map of status codes to arrays of status detail objects.
          additionalProperties:
            type: array
            items:
              type: object
              additionalProperties:
                type: string
    EventResponse:
      type: object
      description: Sourcing event details.
      properties:
        eventId:
          type: integer
          description: Unique identifier for the sourcing event.
        eventName:
          type: string
          description: Name of the sourcing event.
        status:
          type: string
          description: Current status of the event.
    EventListResponse:
      type: object
      description: List of sourcing events.
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/EventResponse'
    AsyncAcceptedResponse:
      type: object
      description: Response returned when an asynchronous operation is accepted.
      properties:
        encodedAsyncPid:
          type: string
          description: Base64-encoded process ID used to poll for status.
  responses:
    Unauthorized:
      description: 'Authentication failed. Ensure a valid OAuth 2.0 bearer token and API key are provided.

        '
    NotFound:
      description: The requested resource was not found.
    UnprocessableEntity:
      description: 'The request was syntactically valid but could not be processed due to validation errors.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 bearer token for authentication.
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-Api-Key
      description: API key passed as a request header.