Charthop org API

openapi: 3.2.0
info:
  description: REST API for ChartHop
  version: V1.0.0
  title: ChartHop access Org API
  contact:
    name: ChartHop
    url: https://www.charthop.com
    email: support@charthop.com
servers:
- url: https://localhost
- url: http://localhost
tags:
- name: org
paths:
  /org/{slug}:
    get:
      tags:
      - org
      summary: Return validation for a org by slug
      operationId: getOrgBySlugNoAuth
      parameters:
      - name: slug
        in: path
        description: Org slug
        required: true
        schema:
          type: string
      responses:
        '400':
          description: bad request
        '404':
          description: not found
  /v1/org:
    get:
      tags:
      - org
      summary: Return all visible orgs, paginated by name
      operationId: findOrgs
      parameters:
      - name: from
        in: query
        description: Org id to start from
        required: false
        schema:
          type: string
      - name: q
        in: query
        description: Search query
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Number of results to return
        required: false
        schema:
          type: integer
          format: int32
      - name: customerId
        in: query
        description: Find orgs belonging to a particular customer id
        required: false
        schema:
          type: string
      - name: realOnly
        in: query
        description: Include only orgs where type is REAL?
        required: false
        schema:
          type: boolean
      - name: lastCreateAt
        in: query
        description: Only include orgs whose last createAt occurred after the date
        required: false
        schema:
          type: string
      - name: lastActiveAt
        in: query
        description: Only include orgs whose last activeAt occurred after the date
        required: false
        schema:
          type: string
      - name: internalOptions
        in: query
        description: Filter orgs by internal option key-value pair
        required: false
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultsOrg'
        '400':
          description: bad request
        '404':
          description: not found
    post:
      tags:
      - org
      summary: Create a new org
      operationId: createOrg
      responses:
        '201':
          description: org created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Org'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrg'
        description: Org data to create
        required: true
  /v1/org/app-install-code/validate:
    post:
      tags:
      - org
      summary: Validate authorization code
      operationId: validateAppInstallAuthorizationCode
      responses:
        '200':
          description: authorization code validated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppInstallCodeValidateResponse'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppInstallCodeValidateRequest'
        description: Authorization code to validate
        required: true
  /v1/org/slug/{slug}:
    get:
      tags:
      - org
      summary: Return a particular org by slug
      operationId: getOrgBySlug
      parameters:
      - name: slug
        in: path
        description: Org slug
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Org'
        '400':
          description: bad request
        '404':
          description: not found
  /v1/org/{orgId}:
    get:
      tags:
      - org
      summary: Return a particular org by id
      operationId: getOrg
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Org'
        '400':
          description: bad request
        '404':
          description: not found
    patch:
      tags:
      - org
      summary: Update an existing org
      operationId: updateOrg
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      responses:
        '204':
          description: org updated
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOrg'
        description: Org data to update
        required: true
  /v1/org/{orgId}/access:
    get:
      tags:
      - org
      summary: Return information on current user's access
      operationId: getUserAccess
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
  /v1/org/{orgId}/agreement:
    post:
      tags:
      - org
      summary: Consent on Terms of Service agreement
      operationId: consentServiceAgreement
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      responses:
        '400':
          description: bad request
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgreementRequest'
        required: true
  /v1/org/{orgId}/copy-self-serve-demo-data:
    post:
      tags:
      - org
      summary: Copy self serve demo data into an org
      operationId: copySelfServeDemoData
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Process'
        '400':
          description: invalid parameters
        '401':
          description: not authorized
        '403':
          description: permission denied
  /v1/org/{orgId}/data-user-person-count:
    get:
      tags:
      - org
      summary: Gets the count of joined users, invited users, and org members who are not yet invited
      operationId: getOrgUserPersonCount
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgUsersPersonsCountResponse'
        '400':
          description: bad request
        '404':
          description: not found
  /v1/org/{orgId}/data-users-persons:
    get:
      tags:
      - org
      summary: Gets a list of org users (joined or invited) and org members (not yet invited)
      operationId: getOrgUsersAndPeople
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: limit
        in: query
        description: limit
        required: false
        schema:
          type: integer
          format: int32
      - name: offset
        in: query
        description: offset
        required: false
        schema:
          type: integer
          format: int32
      - name: includeUsersOnly
        in: query
        description: Include created users only
        required: false
        schema:
          type: boolean
      - name: returnAccess
        in: query
        description: 'Return access information -- pass a list of actions to check, for example: create,update,delete'
        required: false
        schema:
          type: string
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgUsersPersonsResponse'
        '400':
          description: bad request
        '404':
          description: not found
  /v1/org/{orgId}/test-email:
    post:
      tags:
      - org
      summary: Send a test welcome email to oneself
      operationId: sendTestEmail
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      responses:
        '400':
          description: bad request
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TestEmailRequest'
        required: true
  /v1/org/{orgId}/welcome-email:
    get:
      tags:
      - org
      summary: Gets the custom setting or default for the welcome email's subject, body, cta button label
      operationId: getWelcomeEmailSettings
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: isPreboarding
        in: query
        description: Is preboarding
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WelcomeEmailSettings'
        '403':
          description: Permission denied
        '500':
          description: Service error
  /v1/org/{org}/app-install-code:
    post:
      tags:
      - org
      summary: Retrieve an Oauth2 authorization code to install an app at this org
      operationId: getAppInstallAuthorizationCode
      parameters:
      - name: org
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      responses:
        '201':
          description: authorization code created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessTokenResponse'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
components:
  schemas:
    LogData:
      type: object
      required:
      - level
      - at
      - data
      properties:
        level:
          type: string
          enum:
          - INFO
          - WARN
          - ERROR
        at:
          type: string
          description: created timestamp
          example: '2017-01-24T13:57:52Z'
        message:
          type: string
        data:
          type: object
          additionalProperties:
            type: object
    AccessTokenResponse:
      type: object
      required:
      - access_token
      - expires_in
      properties:
        access_token:
          type: string
          description: access token value
          readOnly: true
          example: 2YotnFZFEjr1zCsicMWsdv
        token_type:
          type: string
          description: access token type
          readOnly: true
          example: bearer
        expires_in:
          type: integer
          format: int32
          description: expiration time of token, in seconds
          readOnly: true
          example: '86400'
        refresh_token:
          type: string
          description: refresh token value
          readOnly: true
          example: tGzv3JOkF0XG5Qx2TlKWIA
        scope:
          type: string
          description: scope of the access token
          readOnly: true
          example: admin
        redirect_uri:
          type: string
          description: redirect uri of the access token
          readOnly: true
          example: com.charthop.mobile://oauth
    UserListRow:
      type: object
      required:
      - name
      - inviteStatus
      - isOrgMember
      properties:
        name:
          $ref: '#/components/schemas/Name'
        inviteStatus:
          type: string
          enum:
          - INVITED
          - JOINED
          - NOT_INVITED
        isOrgMember:
          type: boolean
        userId:
          type: string
          example: 588f7ee98f138b19220041a7
        personId:
          type: string
          example: 588f7ee98f138b19220041a7
        imagePath:
          type: string
        email:
          type: string
        access:
          type: string
        roleLabel:
          type: string
        roleId:
          type: string
          example: 588f7ee98f138b19220041a7
        expr:
          type: string
        groupIds:
          type: array
          uniqueItems: true
          items:
            type: string
            example: 588f7ee98f138b19220041a7
        loginAt:
          type: string
        userStatus:
          type: string
          enum:
          - INACTIVE
          - PREBOARDING
          - ACTIVATION
          - ACTIVE
          - OFFBOARDED
        activeAt:
          type: string
        createId:
          type: string
        updateId:
          type: string
        updateAt:
          type: string
    AppInstallCodeValidateResponse:
      type: object
      required:
      - userId
      properties:
        userId:
          type: string
          description: userId that created the app install authorization code
          example: 64b050ef762ef7deb38ac723
        data:
          type: object
          description: data associated with the app install authorization code
          example: '{ "orgId": "64b05135e1342073d3d45984" }'
        accessToken:
          type: string
          description: access token issued from app install authorization code
    Address:
      type: object
      required:
      - country
      properties:
        street1:
          type: string
          description: street address, line 1
          example: 123 Anywhere Street
          minItems: 0
          maxItems: 200
        street2:
          type: string
          description: street address, line 2
          example: Apt 6L
          minItems: 0
          maxItems: 200
        street3:
          type: string
          description: street address, line 3
          example: Sixth Floor
          minItems: 0
          maxItems: 200
        city:
          type: string
          description: city
          example: New York
          minItems: 0
          maxItems: 80
        state:
          type: string
          description: state
          example: NY
          minItems: 0
          maxItems: 80
        country:
          type: string
          description: country (two-digit ISO code)
          example: NY
          pattern: ^[A-Z]{2}$
        postal:
          type: string
          description: postal code
          example: '10001'
          minItems: 0
          maxItems: 10
        geo:
          description: geopoint location
          $ref: '#/components/schemas/Geopoint'
        approxGeo:
          description: approximate geopoint location (suitable for a map placement, but not exact location)
          $ref: '#/components/schemas/Geopoint'
    OrgUsersPersonsCountResponse:
      type: object
      required:
      - joinedCount
      - invitedCount
      - notInvitedCount
      properties:
        joinedCount:
          type: integer
          format: int32
        invitedCount:
          type: integer
          format: int32
        notInvitedCount:
          type: integer
          format: int32
    ResultsOrg:
      type: object
      required:
      - data
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Org'
        next:
          type: string
    InternalOrgOptions:
      type: object
      properties:
        adpOrganizationOID:
          type: string
        assessmentCount:
          type: integer
          format: int32
        dashboardGettingStartedHidden:
          type: boolean
        dashboardNeedHelpHidden:
          type: boolean
        enableUniversalSso:
          type: boolean
        sequoiaOrgId:
          type: string
        tosAgreement:
          type: boolean
        fileUploadLimit:
          type: integer
          format: int64
        maxFileUploadSize:
          type: integer
          format: int64
        lowPriorityReports:
          type: boolean
        isInitialDataSynced:
          type: boolean
        maxReportDatapoints:
          type: integer
          format: int64
        disableImportEvents:
          type: boolean
          description: Whether to disable event notifications on imports -- should only be used temporarily in performance-critical initial imports
        useAlphaSlackApp:
          type: boolean
          description: Use the alpha Slack app (a second real Slack app sharing the global 'slack' install) instead of the default for inbound hooks and outbound messages — ChartHop-staff only, for Slack-team app-review testing
        extraFields:
          type: object
          additionalProperties:
            type: object
    Org:
      type: object
      required:
      - id
      - name
      - slug
      - options
      properties:
        id:
          type: string
          description: globally unique id
          example: 588f7ee98f138b19220041a7
        customerId:
          type: string
          description: customer for billing processing
          example: 588f7ee98f138b19220041a7
        name:
          type: string
          description: name of organization
          example: Acme Corp
        slug:
          type: string
          description: unique slug of organization
          example: acme-corp
        type:
          type: string
          description: type of organization
          example: PRIVATE
          enum:
          - PRIVATE
          - PUBLIC
          - EDU
          - GOV
          - NONPROFIT
          - DEMO
          - TEST
          - PORTFOLIO
        industry:
          type: string
          description: industry
          example: Software and Internet
        estEmployees:
          type: integer
          format: int32
          description: approximate number of employees
        estRevenue:
          type: integer
          format: int32
          description: approximate amount of revenue
        foundedYear:
          type: string
          description: year of founding
          example: '1998'
        address:
          description: street address
          $ref: '#/components/schemas/Address'
        phone:
          type: string
          description: company phone number in E.164 format
          pattern: ^\+?[1-9]\d{1,14}$
        email:
          type: string
          description: primary contact email
          example: bob@example.com
        url:
          type: string
          format: uri
          description: website URL
        domains:
          type: array
          description: domains used by this org
          items:
            $ref: '#/components/schemas/OrgDomain'
        status:
          type: string
          description: current status of organization
          enum:
          - ACTIVE
          - INACTIVE
          - DISABLED
        imagePath:
          type: string
          description: path to full-sized profile image in storage
          pattern: ^[a-zA-Z0-9._/-]+$
        currencies:
          type: array
          description: types of currencies in use, with the first currency the primary currency
          items:
            type: string
          minItems: 1
          maxItems: 100
        locales:
          type: array
          description: locales supported within the org based on user selection, with the first locale the primary locale (e.g., en_US, en_GB, fr_FR, fr_CA)
          items:
            type: string
        dataResidency:
          type: string
          description: data residency of the org - the db cluster where this org's data resides
          enum:
          - GLOBAL
          - US
          - EU
        stock:
          type: string
          description: stock symbol
          example: GOOG
        timezone:
          type: string
          description: timezone in use
          example: America/New_York
        appTimes:
          type: array
          description: approximate times of day in the org timezone for daily app syncs to run (if unset, syncs will run 2am-8am US Eastern Time)
          example: 09:00
          items:
            type: string
        fiscalStart:
          type: integer
          format: int32
          description: number of months into the calendar year that the fiscal year starts (1 = February, 2 = March)
        headJobId:
          type: string
          description: head of the organization
          example: 588f7ee98f138b19220041a7
        unassignedManagerJobId:
          type: string
          description: Job ID that all jobs with missing manager report to in the organization
          example: 588f7ee98f138b19220041a7
        portfolioParentOrgId:
          type: string
          description: portfolio parent org ID
          example: 588f7ee98f138b19220041a7
        startDate:
          type: string
          format: date
          description: start date of history
        options:
          description: org-public options
          $ref: '#/components/schemas/OrgOptions'
        internalOptions:
          description: internal (ChartHop controlled) options
          $ref: '#/components/schemas/InternalOrgOptions'
        onboarding:
          type: boolean
          description: current onboarding status of an organization, allowing clearing of org
        selfServeImporting:
          type: boolean
          description: completion status of initial import for orgs signed up via self serve
        headCount:
          type: integer
          format: int32
          description: number of total headcount currently in the org
        userCount:
          type: integer
          format: int32
          description: number of non-ChartHop, non-app users in the org
        activeUserCount:
          type: integer
          format: int32
          description: number of non-ChartHop, non-app users in the org active in the past month
        activeAt:
          type: string
          description: last timestamp that any user was active in the org
          example: '2017-01-24T13:57:52Z'
        createId:
          type: string
          description: created by user id
          example: 588f7ee98f138b19220041a7
        createBehalfId:
          type: string
          description: created on behalf of user id
          example: 588f7ee98f138b19220041a7
        createAttribution:
          $ref: '#/components/schemas/Attribution'
        createAt:
          type: string
          description: created timestamp
          example: '2017-01-24T13:57:52Z'
        updateId:
          type: string
          description: last updated by user id
          example: 588f7ee98f138b19220041a7
        updateBehalfId:
          type: string
          description: last updated on behalf of user id
          example: 588f7ee98f138b19220041a7
        updateAttribution:
          $ref: '#/components/schemas/Attribution'
        updateAt:
          type: string
          description: last updated timestamp
          example: '2017-01-24T13:57:52Z'
        destroyAt:
          type: string
          description: timestamp that the org is marked for data destruction
          readOnly: true
          example: '2017-01-24T13:57:52Z'
        destroyId:
          type: string
          description: user who marked the org for data destruction
          readOnly: true
          example: 588f7ee98f138b19220041a7
        destroyedAt:
          type: string
          description: date at which this org was destroyed, can not be modified
          readOnly: true
    LayoutButton:
      type: object
      required:
      - url
      - label
      properties:
        url:
          type: string
        label:
          type: string
    ResultsAccess:
      type: object
      required:
      - allowed
      properties:
        ids:
          type: array
          uniqueItems: true
          items:
            type: string
            example: 588f7ee98f138b19220041a7
        allowed:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/AccessAction'
    Geopoint:
      type: object
      required:
      - type
      - coordinates
      properties:
        type:
          type: string
          description: Type of point
          readOnly: true
        coordinates:
          type: array
          description: The longitude and latitude of the point
          readOnly: true
          items:
            type: number
            format: double
    MessageChannelConfig:
      type: object
      required:
      - channels
      - alwaysEmail
      properties:
        channels:
          type: array
          items:
            type: string
            enum:
            - EMAIL
            - CHAT
            - CHAT_SLACK
            - CHAT_TEAMS
        alwaysEmail:
          type: boolean
    OrgDomain:
      type: object
      required:
      - domain
      - aliases
      properties:
        domain:
          type: string
        aliases:
          type: array
          uniqueItems: true
          items:
            type: string
    AccessAction:
      type: object
      required:
      - action
      properties:
        action:
          type: string
        fields:
          type: array
          uniqueItems: true
          items:
            type: string
        types:
          type: array
          uniqueItems: true
          items:
            type: string
    Name:
      type: object
      required:
      - last
      properties:
        first:
          type: string
          description: first name
          example: Jane
          minItems: 0
          maxItems: 80
        middle:
          type: string
          description: middle name
          example: Quidditch
          minItems: 0
          maxItems: 80
        last:
          type: string
          description: last name
          example: Public
          minItems: 0
          maxItems: 80
        pref:
          type: string
          description: preferred first name
          example: JQ
          minItems: 0
          maxItems: 80
        prefLast:
          type: string
          description: preferred last name
          example: Smith
          minItems: 0
          maxItems: 80
    Process:
      type: object
      required:
      - id
      - orgId
      - label
      - type
      - status
      - runUserId
      - createId
      - createAt
      - options
      properties:
        id:
          type: string
          description: globally unique id
          example: 588f7ee98f138b19220041a7
        orgId:
          type: string
          description: parent org id
          example: 588f7ee98f138b19220041a7
        label:
          type: string
          description: human-readable label that identifies this process
        type:
          type: string
          description: process type
        status:
          type: string
          description: current status of process
          enum:
          - PENDING
          - RUNNING
          - DONE
          - ERROR
        filePath:
          type: string
          description: data file path
        logPath:
          type: string
          description: data log path
        runUserId:
          type: string
          description: user id who is running the process
          example: 588f7ee98f138b19220041a7
        parentProcessId:
          type: string
          description: process id of parent process
          example: 588f7ee98f138b19220041a7
        createId:
          type: string
          description: created by user id (user who requested the process run)
          example: 588f7ee98f138b19220041a7
        createBehalfId:
          type: string
          description: created on behalf of user id
          example: 588f7ee98f138b19220041a7
        createAttribution:
          $ref: '#/components/schemas/Attribution'
        createAt:
          type: string
          description: created timestamp
          example: '2017-01-24T13:57:52Z'
        updateId:
          type: string
          description: last updated by user id
          example: 588f7ee98f138b19220041a7
        updateBehalfId:
          type: string
          description: last updated on behalf of user id
          example: 588f7ee98f138b19220041a7
        updateAttribution:
          $ref: '#/components/schemas/Attribution'
        updateAt:
          type: string
          description: last updated timestamp
          example: '2017-01-24T13:57:52Z'
        startAt:
          type: string
          description: started at timestamp
          example: '2017-01-24T13:57:52Z'
        endAt:
          type: string
          description: ended at timestamp
          example: '2017-01-24T13:57:52Z'
        message:
          type: string
          description: status or error message
        progress:
          type: number
          format: double
          description: percent progress so far
        internalError:
          type: string
          description: internal-only error message
        options:
          type: object
          description: options passed to the process
        results:
          type: object
          description: results summary for the process
          additionalProperties:
            type: object
        logDataList:
          type: array
          description: list of log data that occurred during running of this process
          items:
            $ref: '#/components/schemas/LogData'
        state:
          type: object
          description: process-specific state data
        summary:
          type: string
          description: human-readable, searchable summary of what this process did
        appId:
          type: string
          description: app id of the process
          example: 588f7ee98f138b19220041a7
        uuid:
          type: string
          description: unique ID of the process at queue time
          example: 84db3c6e-0877-4436-8af1-768c06b29586
    LayoutRow:
      type: object
      required:
      - columns
      - format
      properties:
        columns:
          type: array
          items:
            $ref: '#/components/schemas/LayoutColumn'
        format:
          type: string
    Attribution:
      type: object
      properties:
        principalUserId:
          type: string
          example: 588f7ee98f138b19220041a7
        agentUserIds:
          type: array
          items:
            type: string
            example: 588f7ee98f138b19220041a7
        eventId:
          type: string
          example: 588f7ee98f138b19220041a7
        aiChatId:
          type: string
          example: 588f7ee98f138b19220041a7
        aiToolUseId:
          type: string
        channel:
          type: string
          enum:
          - WEB
          - MOBILE
          - SLACK
          

# --- truncated at 32 KB (70 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/charthop/refs/heads/main/openapi/charthop-org-api-openapi.yml