YAML Schema

connectors/
└── {provider}/
    ├── {provider}.connector.s1.yaml      # Main connector file
    ├── {provider}.{resource1}.s1.partial.yaml  # Actions partial
    └── {provider}.{resource2}.s1.partial.yaml  # Actions partial

StackOne: 1.0.0

info:
  title: BambooHR

info:
  key: bamboohr

info:
  version: 1.0.0

info:
  assets:
    icon: https://stackone-logos.com/api/bamboohr/filled/svg

info:
  description: BambooHR connector for HRIS actions including employee data, time-off, and reporting

info:
  details: |
    Example HRIS connector covering employees, time off, and reporting.

    Notes:
    - Requires an API key with admin scope for reporting endpoints.
    - Some endpoints may require a paid plan.

info:
  version: 1.2.0
  changelog:
    summary: Added time-off actions and fixed employee pagination.
    labels:
      - new-actions
      - bugfix

baseUrl: 'https://api.bamboohr.com/api/gateway.php'

baseUrl: 'https://api.bamboohr.com/api/gateway.php/${credentials.subdomain}/v1'

baseUrl: 'https://${config.region}.api.provider.com/v2'

rateLimit:
  mainRatelimit: 10

rateLimit:
  mainRatelimit: 10
  subPools:
    - subPoolKey: search
      urlPattern: '/search'
      rateLimit: 2

rateLimit:
  mainRatelimit: 10
  mappedRateLimitErrors:
    - errorStatus: 429
      errorMessage: Too Many Requests
      retryAfterPath: "$['retry-after']"
      retryAfterUnit: seconds

concurrency:
  mainMaxConcurrency: 5
  subPools:
    - subPoolKey: reports
      urlPattern: '/reports'
      maxConcurrency: 1

mcp:
  instructions: |
    Use list_* actions before get_* — most get actions need an ID from a list.
    Employee IDs are numeric strings.

releaseStage: beta

forkedFrom: bamboohr

resources: https://documentation.bamboohr.com/reference

documentation:
  references:
    - title: Microsoft Graph API
      url: https://learn.microsoft.com/en-us/graph/api/overview?view=graph-rest-1.0
      description: Full REST API reference for Microsoft Graph.
    - title: Build a bot for Microsoft Teams
      url: https://learn.microsoft.com/en-us/microsoftteams/platform/bots/what-are-bots
      description: Guide for building bots to leverage the messaging API for agentic use cases.

scopeDefinitions:
  employees:read:
    description: Read employee data
  employees:write:
    description: Create and update employee records
    includes: employees:read

authentication:
  - oauth2:
      type: oauth2
      label: OAuth 2.0
      # ... oauth config
  - api_key:
      type: custom
      label: API Key
      # ... api key config

authentication:
  - oauth2:
      type: oauth2
      grantType: client_credentials   # or authorization_code (default)

authentication:
  - custom:
      type: custom
      certificates:
        certs:
          - $.credentials.clientCert
        keys:
          - $.credentials.clientKey

configNotices:
  - key: sandbox_warning
    type: warning
    description: Use your sandbox subdomain when testing.
    position: top

authentication:
  - custom:
      type: custom
      label: API Key
      support:
        description: Admin privileges required
        guides:
          config:
            warning: Admin access required to generate an API key.
            sections:
              - title: Generating an API Key
                content: |
                  Instructions for finding the API key.
                steps:
                  - title: Navigate to Settings
                    content: |
                      Go to Settings > API in your account.
                  - title: Create Key
                    content: |
                      Click Generate API Key and copy it.
      authorization:
        type: bearer
        token: $.credentials.apiKey
      configFields:
        - key: apiKey
          label: API Key
          type: password
          required: true
          secret: true

sections:
  - title: Section Title
    content: |
      Section overview text.
    list:
      - Bullet one
      - Bullet two
    image:
      src: https://example.com/screenshot.png
      alt: The API settings page
    applicableScopes: employees:read
    steps:
      - title: Step Title
        content: |
          Step instructions.
        displayScopes: true

actions:
  $ref: bamboohr.employees
  $ref: bamboohr.timeoff
  $ref: bamboohr.reports

actionId: list_employees

categories:
  - hris
  - employees

actionType: list

effects:
  - read

label: List Employees

description: List all employees from BambooHR with optional filtering

details: |
  Retrieves a paginated list of all employees from BambooHR.

  Returns employee profiles including:
  - Personal information (name, email, phone)
  - Employment details (department, job title, hire date)
  - Custom fields configured in your BambooHR account

  Use the 'fields' parameter to specify which fields to include.
  Supports filtering by employment status and department.

resources: https://documentation.bamboohr.com/reference/get-employees-directory

executionMode: async

authRequirements:
  oauth2:
    - employees:read
  custom:
    - employees:read

validationRules:
  - rule: atLeastOneOf
    fields: [email, phone]
    errorMessage: Provide at least an email or a phone number.
  - rule: mutuallyExclusive
    fields: [cursor, page]
  - rule: requiredIf
    field: manager_id
    condition:
      field: is_manager
      equals: 'false'

tags:
  - beta
releaseStage: preview
responses:
  - statusCode: 200
    description: Employees returned successfully
  - statusCode: 404
    description: Department not found

schema: employee
schemaType: unified   # or native (default)

cursor:
  enabled: true
  pageSize: 50

compositeIdentifiers:
  enabled: true
  fields:
    - targetFieldKey: id
      components: [company_id, employee_id]

providerEvents:
  - employee.created
  - employee.updated

examples:
  - exampleDescription: Fetch active employees in Engineering
    input:
      status: active
      department: Engineering
    output:
      data:
        - id: '123'
          display_name: Jane Doe

entrypointUrl: /employees/directory
entrypointHttpMethod: get

dataSync:
  allowed: true
  indexField: id
  pagination:
    type: offset
    response:
      dataKey: data.data
    iterator:
      offsetKey: skip
      limitKey: limit
      in: query
  incremental:
    type: time_filter
    iterator:
      key: 'updatedAt[$gt]'
      in: query
    format: iso8601
    response:
      updatedAtPath: updatedAt

inputs:
  - name: employee_id
    type: string
    description: The unique identifier of the employee
    required: true
    in: path
  - name: fields
    type: string
    description: Comma-separated list of fields to include
    required: false
    default: 'firstName,lastName,email'
    in: query
  - name: page_size
    type: number
    description: Number of results per page (max 100)
    required: false
    default: 25
    in: query

inputs:
  - name: status
    type: enum
    description: Filter by employment status
    required: false
    oneOf:
      values:
        - active
        - inactive
    default: active
    in: query

inputs:
  - name: employment_status
    type: enum
    description: Employment status
    required: false
    oneOf:
      ref: employment_status
    in: query

result:
  data: $.steps.transform_response.output.data
  rawRequest: $.steps.fetch_employees.output.request
  rawResponse: $.steps.fetch_employees.output.response

events:
  setup:
    creation:
      steps: [ ... ]
      result: $.steps.create_hook.output.data
    activation:
      steps: [ ... ]        # optional
    deletion:
      steps: [ ... ]
    isConsolidated: false
  actions:
    - actionId: employee_created
      actionType: event
      providerEvents:
        - employee.created
      steps: [ ... ]
  router:
    rules:
      - when: '{{$.body.type == "employee.created"}}'
        then:
          action: employee_created
  externalAccountIdExtractor:
    actionType: custom
    result: $.steps.extract.output.data
  guides:
    setup:
      sections: [ ... ]

router:
  rules:
    - when: '{{$.body.type == "employee.updated"}}'
      then:
        action: employee_updated
        input:
          id: $.body.data.id

value: $.credentials.apiKey
value: $.inputs.employee_id
value: $.steps.fetch_data.output.data.employees

url: '/employees/${inputs.employee_id}/profile'
baseUrl: 'https://api.${credentials.subdomain}.provider.com'

value: '{{$.inputs.status ?? "active"}}'
value: '{{present(inputs.filter) ? inputs.filter : "all"}}'
condition: '{{$.inputs.page_size > 100}}'

steps:
  - stepId: graphql_query
    stepFunction:
      functionName: request
      parameters:
        url: '/graphql'
        method: post
        args:
          - name: query
            value: |
              query ListUsers($first: Int, $after: String) {
                users(first: $first, after: $after) {
                  nodes {
                    id
                    name
                    email
                  }
                  pageInfo {
                    hasNextPage
                    endCursor
                  }
                }
              }
            in: body
          - name: variables
            value:
              first: '{{$.inputs.page_size ?? 50}}'
              after: '{{$.inputs.cursor ?? null}}'
            in: body

- actionId: list_employees
  categories:
    - hris
    - employees
  actionType: list
  effects:
    - read
  label: List Employees
  description: Retrieve a paginated list of employees from BambooHR
  details: |
    Fetches employee records with optional filtering by status and department.

    Returns:
    - Employee ID and display name
    - Email and phone
    - Department and job title
    - Employment status and dates

    Pagination: Returns 25 records per page by default. Use 'next' cursor for more.
  resources: https://documentation.bamboohr.com/reference/get-employees-directory
  inputs:
    - name: status
      type: enum
      description: Filter by employment status
      required: false
      oneOf:
        values:
          - active
          - inactive
      default: active
      in: query
    - name: department
      type: string
      description: Filter by department name
      required: false
      in: query
    - name: page_size
      type: number
      description: Number of results per page (max 100)
      required: false
      default: 25
      in: query
    - name: cursor
      type: string
      description: Pagination cursor from previous response
      required: false
      in: query
  steps:
    - stepId: fetch_employees
      description: Fetch employee directory from BambooHR API
      stepFunction:
        functionName: paginated_request
        parameters:
          baseUrl: 'https://api.bamboohr.com/api/gateway.php'
          url: '/employees/directory'
          method: get
          iterator:
            key: cursor
            in: query
            mode: cursor
          response:
            dataKey: $.employees
            nextKey: $.paging.next
            nextKeyIn: data
          args:
            - name: status
              value: '{{$.inputs.status ?? "active"}}'
              in: query
            - name: department
              value: $.inputs.department
              in: query
              condition: '{{present(inputs.department)}}'
            - name: page_size
              value: '{{$.inputs.page_size ?? 25}}'
              in: query
    - stepId: transform_employees
      description: Map BambooHR fields to standard format
      stepFunction:
        functionName: map_fields
        version: '2'
        parameters:
          fields:
            - targetFieldKey: id
              expression: $.id
              type: string
            - targetFieldKey: display_name
              expression: $.displayName
              type: string
            - targetFieldKey: email
              expression: $.workEmail
              type: string
            - targetFieldKey: department
              expression: $.department
              type: string
            - targetFieldKey: job_title
              expression: $.jobTitle
              type: string
            - targetFieldKey: status
              expression: $.status
              type: string
            - targetFieldKey: hire_date
              expression: $.hireDate
              type: datetime_string
          dataSource: $.steps.fetch_employees.output.data
  result:
    data: $.steps.transform_employees.output.data
    rawRequest: $.steps.fetch_employees.output.request
    rawResponse: $.steps.fetch_employees.output.response