Ritten

Ritten Cases API

Endpoints for accessing CRM cases (admissions pipeline).

Documentation GitHub OpenAPI

Operations 6

GET /cases List cases in a clinic #

POST /cases Create a case #

GET /cases/{id} Retrieve a case by ID #

PATCH /cases/{id} Update a case #

POST /cases/{id}/notes Create a case note #

POST /cases/{id}/action-items Create a case action item #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/ritten-cases-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: External Cases 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: Cases
  description: Endpoints for accessing CRM cases (admissions pipeline).
paths:
  /cases:
    get:
      tags:
      - Cases
      summary: List cases in a clinic
      description: Lists CRM cases (admissions pipeline) in a clinic
      operationId: listCases
      parameters:
      - name: limit
        in: query
        description: How many cases to return at one time (max 20, min 0).
        schema:
          maximum: 20
          minimum: 0
          type: integer
          format: int64
      - name: offset
        in: query
        description: How many cases to skip before returning results. Use for pagination.
        schema:
          minimum: 0
          type: integer
          format: int64
      - 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
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCases'
        400:
          description: Invalid query parameters
    post:
      tags:
      - Cases
      summary: Create a case
      description: Creates a new CRM case (deal). Case status cannot be set during creation; all cases are created with status "new". Tags and caseSource must be provided as plain text names and must match existing values in the system.
      operationId: createCase
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostCaseBody'
      responses:
        200:
          description: Successfully created case
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Case'
        400:
          description: Bad request (validation error, unknown tag or case source)
        401:
          description: Unauthorized
  /cases/{id}:
    get:
      tags:
      - Cases
      summary: Retrieve a case by ID
      description: Returns a single CRM case
      operationId: getCase
      parameters:
      - name: id
        in: path
        description: ID of the case to return
        required: true
        schema:
          type: string
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Case'
        400:
          description: Invalid ID supplied
        404:
          description: Case not found
    patch:
      tags:
      - Cases
      summary: Update a case
      description: Updates an existing CRM case (deal). Case status cannot be updated through this endpoint. Tags and caseSource must be provided as plain text names and must match existing values in the system.
      operationId: updateCase
      parameters:
      - name: id
        in: path
        description: The ID of the case to update
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchCaseBody'
      responses:
        200:
          description: Successfully updated case
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Case'
        400:
          description: Bad request (validation error, unknown tag or case source)
        401:
          description: Unauthorized
        404:
          description: Case not found
  /cases/{id}/notes:
    post:
      tags:
      - Cases
      summary: Create a case note
      description: Adds a plain-text note to an existing CRM case.
      operationId: createCaseNote
      parameters:
      - name: id
        in: path
        description: The ID of the case to add a note to
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostCaseNoteBody'
      responses:
        200:
          description: Successfully created case note
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CaseNote'
        400:
          description: Bad request (validation error)
        401:
          description: Unauthorized
        404:
          description: Case not found
  /cases/{id}/action-items:
    post:
      tags:
      - Cases
      summary: Create a case action item
      description: 'Adds an action item to an existing CRM case. Action items are the follow-up

        tasks shown on the case in-app.


        Newly created action items are always incomplete; completing one is not

        supported through this API. Requests are not idempotent: retrying a

        successful call creates a second action item.'
      operationId: createCaseActionItem
      parameters:
      - name: id
        in: path
        description: The ID of the case to add an action item to
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostCaseActionItemBody'
      responses:
        200:
          description: Successfully created case action item
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CaseActionItem'
        400:
          description: Bad request (validation error, or the case is archived)
        401:
          description: Unauthorized
        404:
          description: Case not found
components:
  schemas:
    Program:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 182c2e54-3494-4b85-aba5-038cf539d5bf
        programName:
          type: string
          example: Residential
        programType:
          type: string
          example: clinical
    CaseNote:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 182c2e54-3494-4b85-aba5-038cf539d5bf
        caseId:
          type: string
          format: uuid
          example: 182c2e54-3494-4b85-aba5-038cf539d5bf
        note:
          type: string
          example: Patient called to confirm intake appointment
        createdAt:
          type: string
          format: date-time
          example: '2024-01-01T00:00:00Z'
        owner:
          $ref: '#/components/schemas/User'
    PostCaseActionItemBody:
      type: object
      required:
      - content
      properties:
        content:
          type: string
          description: The description of the action item
          example: Call the referral source to confirm insurance
    PostCaseNoteBody:
      type: object
      required:
      - note
      properties:
        note:
          type: string
          description: The plain-text content of the note
          example: Patient called to confirm intake appointment
        userId:
          type: string
          format: uuid
          description: Optional ID of the user who wrote the note
          example: 182c2e54-3494-4b85-aba5-038cf539d5bf
    PostCaseBody:
      type: object
      required:
      - caseName
      properties:
        caseName:
          type: string
          description: Name of the case (required)
          example: John Doe
        personSeekingTreatmentId:
          type: string
          format: uuid
          description: ID of the person seeking treatment
        caseOwnerId:
          type: string
          format: uuid
          description: ID of the staff member who owns this case
        contactIds:
          type: array
          items:
            type: string
            format: uuid
          description: IDs of contacts associated with this case
        caseSource:
          type: string
          description: Name of the case source (must match an existing case source)
          example: Website
        caseSizeCents:
          type: integer
          minimum: 0
          description: Case value in cents
          example: 10000
        potentialAdmitDate:
          type: string
          format: date-time
          description: Potential admission date (ISO 8601)
          example: '2024-01-01T00:00:00Z'
        followUpDate:
          type: string
          format: date-time
          description: Follow-up date (ISO 8601)
          example: '2024-01-15T00:00:00Z'
        potentialProgramIds:
          type: array
          items:
            type: string
            format: uuid
          description: IDs of potential programs for this case
        tags:
          type: array
          items:
            type: string
          description: Tag names to apply to the case (must match existing tags)
          example:
          - urgent
          - self-referral
        createdAt:
          type: string
          format: date-time
          description: Creation date (must be in the past, defaults to today if not provided)
          example: '2024-01-01T00:00:00Z'
    ListCases:
      type: array
      items:
        $ref: '#/components/schemas/Case'
    User:
      type: object
      properties:
        id:
          type: string
          example: 182c2e54-3494-4b85-aba5-038cf539d5bf
        email:
          type: string
          example: johndoe@ritclinic.ritten.io
        first:
          type: string
          example: Doe
        middle:
          type: string
        last:
          type: string
          example: John
        lastAccessedAt:
          type: string
          format: date-time
          nullable: true
          description: Timestamp of the user's most recent app session start (set when the user loads the app). Null if the user has never logged in.
          example: '2024-01-15T14:32:00Z'
    CaseContact:
      type: object
      description: 'A contact as it appears on a case. Deliberately narrower than the Contact returned by

        the /contacts endpoints: it carries identity only, with no email or organizations.

        '
      properties:
        id:
          type: string
          example: 182c2e54-3494-4b85-aba5-038cf539d5bf
        first:
          type: string
          example: John
        middle:
          type: string
        last:
          type: string
          example: Doe
        dob:
          type: string
          description: Always empty on this surface. Use GET /contacts/{id} for a contact's date of birth.
          example: ''
        mrn:
          type: string
          description: Ritten Medical Record Number (if applicable)
        createdAt:
          type: string
          format: date-time
          description: Contact record creation timestamp.
          example: '2024-01-01T00:00:00Z'
    CaseActionItem:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 182c2e54-3494-4b85-aba5-038cf539d5bf
        caseId:
          type: string
          format: uuid
          example: 182c2e54-3494-4b85-aba5-038cf539d5bf
        content:
          type: string
          example: Call the referral source to confirm insurance
        isComplete:
          type: boolean
          example: false
        completedAt:
          type: string
          format: date-time
          nullable: true
          example: null
        completedBy:
          allOf:
          - $ref: '#/components/schemas/User'
          nullable: true
        createdAt:
          type: string
          format: date-time
          example: '2024-01-01T00:00:00Z'
    Case:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 182c2e54-3494-4b85-aba5-038cf539d5bf
        caseName:
          type: string
          example: John Doe
        status:
          type: string
          example: New
        caseSource:
          type: string
        caseSizeCents:
          type: integer
          description: Case value in cents
          example: 10000
        potentialAdmitDate:
          type: string
          format: date-time
          example: '2024-01-01T00:00:00Z'
        followUpDate:
          type: string
          format: date-time
          example: '2024-01-15T00:00:00Z'
        createdAt:
          type: string
          format: date-time
          example: '2024-01-01T00:00:00Z'
        personSeekingTreatment:
          $ref: '#/components/schemas/CaseContact'
        caseOwner:
          $ref: '#/components/schemas/User'
        contacts:
          type: array
          items:
            $ref: '#/components/schemas/CaseContact'
        potentialPrograms:
          type: array
          items:
            $ref: '#/components/schemas/Program'
        tags:
          type: array
          items:
            type: string
    PatchCaseBody:
      type: object
      properties:
        caseName:
          type: string
          description: Name of the case
          example: John Doe
        personSeekingTreatmentId:
          type: string
          format: uuid
          description: ID of the person seeking treatment
        caseOwnerId:
          type: string
          format: uuid
          description: ID of the staff member who owns this case
        contactIds:
          type: array
          items:
            type: string
            format: uuid
          description: IDs of contacts associated with this case (replaces existing)
        caseSource:
          type: string
          description: Name of the case source (must match an existing case source)
          example: Website
        caseSizeCents:
          type: integer
          minimum: 0
          description: Case value in cents
          example: 10000
        potentialAdmitDate:
          type: string
          format: date-time
          description: Potential admission date (ISO 8601)
          example: '2024-01-01T00:00:00Z'
        followUpDate:
          type: string
          format: date-time
          description: Follow-up date (ISO 8601)
          example: '2024-01-15T00:00:00Z'
        potentialProgramIds:
          type: array
          items:
            type: string
            format: uuid
          description: IDs of potential programs for this case (replaces existing)
        tags:
          type: array
          items:
            type: string
          description: Tag names to apply to the case (replaces existing tags, must match existing tags)
          example:
          - urgent
          - self-referral
        createdAt:
          type: string
          format: date-time
          description: Creation date (must be in the past)
          example: '2024-01-01T00:00:00Z'