Ritten Organizations API

openapi: 3.2.0
info:
  title: External Organizations API
  x-logo:
    url: https://storage.googleapis.com/ritten-ops-public-logos/rittenBanner
    backgroundColor: '#FFFFFF'
    altText: Ritten Logo
  description: 'For Ritten Integrating Partners


    ## Authentication


    - Request an access token with your provided integration credentials (`client_id` and `client_secret`) by calling our token endpoint:

    ```bash

    curl https://api.ritten.io/v1/oauth/token \

    -X POST \

    -H ''content-type: application/json'' \

    -d ''{"client_id":"${client_id}","client_secret":"${client_secret}","audience":"https://external-api.ritten.io","grant_type":"client_credentials"}''

    ```

    - Take the `access_token` from the response and use that as…'
  version: 1.0.0
servers:
- url: https://api.ritten.io/v1
tags:
- name: Organizations
  description: Endpoints for accessing CRM organizations and organization members. Requires CRM to be available for the target clinic (`X-Ritten-Tenant`). Integrations must be explicitly provisioned by Ritten for organization access.
paths:
  /organizations:
    get:
      tags:
      - Organizations
      summary: List active organizations in a clinic
      description: Lists active CRM organizations with pagination and optional filters. Requires CRM to be available for the target clinic and organization access to be granted by Ritten.
      operationId: listOrganizations
      parameters:
      - name: search
        in: query
        description: Case-insensitive search on organization name.
        schema:
          type: string
      - name: organizationTypeIds
        in: query
        description: Filter by one or more organization type IDs.
        schema:
          type: array
          items:
            type: string
            format: uuid
        style: form
        explode: true
      - name: assignedUserIds
        in: query
        description: Filter by one or more assigned user IDs.
        schema:
          type: array
          items:
            type: string
            format: uuid
        style: form
        explode: true
      - name: tagIds
        in: query
        description: Filter by one or more tag IDs.
        schema:
          type: array
          items:
            type: string
            format: uuid
        style: form
        explode: true
      - name: matchAllTags
        in: query
        description: When true, only return records that have ALL selected tags (AND). Default false returns records matching ANY selected tag (OR).
        schema:
          type: boolean
          default: false
      - name: sortBy
        in: query
        description: Sort order for returned organizations.
        schema:
          type: string
          enum:
          - name_asc
          - name_desc
          - createdAt_asc
          - createdAt_desc
      - name: limit
        in: query
        description: How many organizations to return at one time (max 20).
        schema:
          maximum: 20
          minimum: 1
          type: integer
          format: int64
          default: 20
      - name: offset
        in: query
        description: How many organizations to skip before returning results. Use for pagination.
        schema:
          minimum: 0
          type: integer
          format: int64
          default: 0
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListOrganizations'
        400:
          description: Invalid query parameters
        403:
          description: CRM is not available for this clinic or this integration has not been granted organization access. Contact Ritten to enable access.
    post:
      tags:
      - Organizations
      summary: Create an organization in a clinic
      description: Creates a CRM organization with optional contact, website, address, assigned user, and primary contact information. Requires CRM to be available for the target clinic and organization access to be granted by Ritten.
      operationId: postOrganization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostOrganizationBody'
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
        400:
          description: Invalid payload supplied
        403:
          description: CRM is not available for this clinic or this integration has not been granted organization access. Contact Ritten to enable access.
  /organizations/{id}:
    get:
      tags:
      - Organizations
      summary: Get an active organization
      description: Returns a single active CRM organization by ID. Requires CRM to be available for the target clinic and organization access to be granted by Ritten.
      operationId: getOrganization
      parameters:
      - name: id
        in: path
        required: true
        description: Organization ID.
        schema:
          type: string
          format: uuid
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
        400:
          description: Invalid organization ID
        403:
          description: CRM is not available for this clinic or this integration has not been granted organization access. Contact Ritten to enable access.
        404:
          description: Organization not found
    patch:
      tags:
      - Organizations
      summary: Update an organization
      description: Updates direct flat fields on an active CRM organization. Nested resources such as contact points, tags, addresses, and primary contacts are not supported by this endpoint. Requires CRM to be available for the target clinic and organization access to be granted by Ritten.
      operationId: patchOrganization
      parameters:
      - name: id
        in: path
        required: true
        description: Organization ID.
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchOrganizationBody'
      responses:
        204:
          description: Organization updated successfully.
        400:
          description: Invalid payload supplied
        403:
          description: CRM is not available for this clinic or this integration has not been granted organization access. Contact Ritten to enable access.
        404:
          description: Organization not found
  /organizations/{id}/members:
    get:
      tags:
      - Organizations
      summary: List active organization members
      description: Lists member relationships for an active CRM organization. Requires CRM to be available for the target clinic and organization access to be granted by Ritten.
      operationId: listOrganizationMembers
      parameters:
      - name: id
        in: path
        required: true
        description: Organization ID.
        schema:
          type: string
          format: uuid
      - name: limit
        in: query
        description: How many members to return at one time (max 20).
        schema:
          maximum: 20
          minimum: 1
          type: integer
          format: int64
          default: 20
      - name: offset
        in: query
        description: How many members to skip before returning results. Use for pagination.
        schema:
          minimum: 0
          type: integer
          format: int64
          default: 0
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListOrganizationMembers'
        400:
          description: Invalid query parameters
        403:
          description: CRM is not available for this clinic or this integration has not been granted organization access. Contact Ritten to enable access.
        404:
          description: Organization not found
components:
  schemas:
    OrganizationMember:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Organization-person relationship ID.
        personId:
          type: string
          format: uuid
        first:
          type: string
          example: Jane
        last:
          type: string
          example: Doe
    Organization:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          example: Ritten Recovery Center
        typeId:
          type: string
          format: uuid
          description: Organization type ID.
        assignedUserId:
          type: string
          format: uuid
          description: User assigned to the organization, if any.
        website:
          type: string
          format: uri
          description: Organization website URL.
          example: https://example.com
        createdAt:
          type: string
          format: date-time
          example: '2024-01-01T00:00:00Z'
    PostOrganizationAddress:
      type: object
      properties:
        country:
          type: string
          example: US
        line:
          type: string
          description: Street address line 1.
          example: 123 Main St
        line2:
          type: string
          description: Street address line 2.
          example: Suite 100
        city:
          type: string
          example: New York
        region:
          type: string
          example: NY
        postalCode:
          type: string
          example: '10001'
        notes:
          type: string
          example: Main admissions office
    ListOrganizations:
      type: object
      properties:
        meta:
          type: object
          properties:
            count:
              type: integer
              example: 1
            totalCount:
              type: integer
              example: 10
        organizations:
          type: array
          items:
            $ref: '#/components/schemas/Organization'
    PostOrganizationBody:
      type: object
      additionalProperties: false
      required:
      - name
      - typeId
      properties:
        name:
          type: string
          description: Organization name.
          example: Ritten Recovery Center
        typeId:
          type: string
          format: uuid
          description: Organization type ID.
        email:
          type: string
          format: email
          description: Primary work email for the organization.
          example: admissions@example.com
        phone:
          type: string
          description: Primary work phone for the organization.
          example: 555-555-5555
        website:
          type: string
          format: uri
          description: Organization website URL.
          example: https://example.com
        address:
          $ref: '#/components/schemas/PostOrganizationAddress'
        assignedUserId:
          type: string
          format: uuid
          description: User assigned to the organization.
        primaryContactId:
          type: string
          format: uuid
          description: Person to set as the organization's primary contact.
    PatchOrganizationBody:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          description: Organization name. Leading and trailing whitespace is trimmed.
          example: Ritten Recovery Center
        typeId:
          type: string
          format: uuid
          description: Organization type ID.
        assignedUserId:
          type: string
          format: uuid
          description: User assigned to the organization.
        website:
          type: string
          format: uri
          description: Organization website URL.
          example: https://example.com
    ListOrganizationMembers:
      type: object
      properties:
        meta:
          type: object
          properties:
            count:
              type: integer
              example: 1
            totalCount:
              type: integer
              example: 10
        members:
          type: array
          items:
            $ref: '#/components/schemas/OrganizationMember'
x-provenance:
  method: harvested
  publisher: Ritten
  source: https://docs.ritten.io/swagger/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)