General Collaborators API

Endpoints for managing collaborators and external partners.

List Collaborators

Get a list of collaborators.

Endpoint: GET /v1/collaborators
Authentication: Required

Query Parameters

Example Request

GET /v1/collaborators?type=school&status=active HTTP/1.1
Content-Type: application/json
X-User-Token: your_token_here

Create Collaborator

Endpoint: POST /v1/collaborators
Authentication: Required

Request Body Parameters

Example Request

POST /v1/collaborators HTTP/1.1
Content-Type: application/json
X-User-Token: your_token_here
 
{
  "collaborator": {
    "first_name": "Sarah",
    "last_name": "Johnson",
    "email": "[email protected]",
    "phone": "+1-555-987-6543",
    "organization": "Lincoln Elementary School",
    "title": "School Counselor",
    "type": "school",
    "specialization": "behavioral_support"
  }
}

Update Collaborator

Endpoint: PUT /v1/collaborators/{id}
Authentication: Required

Path Parameters

Request Body Parameters

Same as Create Collaborator endpoint, but all fields are optional.

Get Collaborator Details

Endpoint: GET /v1/collaborators/{id}
Authentication: Required

Path Parameters

Example Request

GET /v1/collaborators/123 HTTP/1.1
Content-Type: application/json
X-User-Token: your_token_here

Delete Collaborator

Endpoint: DELETE /v1/collaborators/{id}
Authentication: Required

Path Parameters

Collaborator Assessments

Create Collaborator Assessment

Endpoint: POST /v1/collaborator_assessments
Authentication: Required

Request Body Parameters

Example Request

POST /v1/collaborator_assessments HTTP/1.1
Content-Type: application/json
X-User-Token: your_token_here
 
{
  "collaborator_assessment": {
    "collaborator_id": 123,
    "patient_id": 1049,
    "assessment_type": "behavioral_observation",
    "responses": [
      {
        "question_id": 1,
        "answer": "Often"
      },
      {
        "question_id": 2,
        "answer": "Moderate improvement"
      }
    ]
  }
}

Get Assessment Token

Get a secure token for collaborator assessment access.

Endpoint: GET /v1/collaborator_assessments/token
Authentication: Required

Query Parameters

Example Request

GET /v1/collaborator_assessments/token?collaborator_id=123&patient_id=1049&assessment_type=behavioral_observation HTTP/1.1
Content-Type: application/json
X-User-Token: your_token_here

Response Format

Collaborator Response

{
  "id": 123,
  "first_name": "Sarah",
  "last_name": "Johnson",
  "email": "[email protected]",
  "phone": "+1-555-987-6543",
  "organization": "Lincoln Elementary School",
  "title": "School Counselor",
  "type": "school",
  "specialization": "behavioral_support",
  "status": "active",
  "created_at": "2023-10-20T10:00:00.000Z",
  "updated_at": "2023-10-20T15:30:00.000Z"
}

Collaborator Assessment Response

{
  "id": 456,
  "collaborator_id": 123,
  "patient_id": 1049,
  "assessment_type": "behavioral_observation",
  "status": "completed",
  "responses": [
    {
      "question_id": 1,
      "question_text": "How often does the student display disruptive behavior?",
      "answer": "Often",
      "score": 3
    }
  ],
  "completed_at": "2023-10-27T14:30:00.000Z",
  "created_at": "2023-10-27T14:00:00.000Z"
}

Assessment Token Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2023-10-28T14:30:00.000Z",
  "assessment_url": "https://assessments.example.com/collaborate/abc123"
}

Collaborator Types

• school - School personnel (teachers, counselors, etc.)
• therapist - External therapists
• physician - Medical doctors
• social_worker - Social workers
• case_manager - Case managers
• family_member - Family members
• other - Other types of collaborators

Collaborator Status Values

• active - Collaborator is active
• inactive - Collaborator is inactive
• pending - Collaborator invitation pending
• declined - Collaborator declined invitation
• suspended - Collaborator access suspended

Assessment Types

• behavioral_observation - Behavioral observation assessment
• academic_performance - Academic performance evaluation
• social_skills - Social skills assessment
• progress_report - Progress report
• incident_report - Incident or behavior report
• treatment_feedback - Treatment feedback

Specializations

• behavioral_support - Behavioral support specialist
• academic_support - Academic support specialist
• speech_therapy - Speech and language therapy
• occupational_therapy - Occupational therapy
• physical_therapy - Physical therapy
• special_education - Special education
• general_education - General education

Error Responses

422 Unprocessable Entity

{
  "errors": {
    "email": ["can't be blank", "has already been taken"],
    "organization": ["can't be blank"],
    "type": ["is not included in the list"]
  }
}

404 Not Found

{
  "errors": "Collaborator not found"
}

403 Forbidden

{
  "errors": "You are not authorized to access this collaborator"
}

Notes

• Collaborators provide external perspectives on patient progress
• Assessment tokens provide secure, time-limited access for external assessments
• Different collaborator types may have access to different assessment tools
• All collaborator interactions are logged for audit and compliance purposes
• Collaborator assessments help provide comprehensive patient evaluations
• Organizations help group collaborators for easier management
• Specializations help match collaborators with appropriate assessment types