Coram Ai reunification API

openapi: 3.2.0
info:
  title: Coram Reunification API
  description: '# Introduction


    The Coram API enables seamless programmatic access to your security camera infrastructure, allowing you to build custom integrations and automate workflows.'
  version: 1.0.0
servers:
- url: https://developer.coram.ai
  description: Production
security:
- X-Auth-Token: []
tags:
- name: reunification
  description: Bulk-import your school reunification roster — schools, students (with guardians), teachers, staff, and class sections — programmatically, the API equivalent of the in-app CSV upload. Each import is a full roster replace; poll the status endpoint for completion and partial-success counts.
paths:
  /v1/reunification/imports:
    post:
      operationId: create_reunification_import
      summary: Import reunification roster data
      description: 'Bulk-imports reunification roster data — schools, students (with their

        guardians), teachers, and staff — as JSON. The programmatic equivalent

        of the in-app CSV upload.


        **This is a full roster replace, not a partial update.** Each call

        replaces the organization''s entire reunification roster: every person

        and school you send is inserted or updated, and **anything you omit is

        removed**. To keep someone, include them in every import; to remove

        someone, send a roster without them. Always send the complete roster —

        sending only `students`, for example, would delete all schools,

        teachers, and sections. To guard against that, the `schools`,

        `students`, `teachers`, and `sections` keys are **required to be

        present** (they may be empty arrays); `staff` is optional. This mirrors

        the in-app CSV upload, which requires every file.


        List each student, teacher, and staff member **once**. To place a person

        in multiple schools, put every school id in `school_ids` on that single

        object — a repeated `student_id`/`teacher_id`/`staff_id` is rejected

        (`400`), not merged.


        Cross-references are resolved against the ids in this same payload, so

        list an entity before you reference it. A `school_id`, `student_id`, or

        `teacher_id` that doesn''t resolve to something in the payload is

        silently skipped — the surrounding record is still imported, just

        without that link — so a mistyped id quietly drops a school membership

        or section rather than failing the import.


        Processing runs asynchronously and respects the same Auth0 rate limits

        as the in-app flow; only one import per organization runs at a time —

        a request made while one is already running returns `409`. The `202`

        response is the initial in-progress status — poll

        `GET /reunification/imports/status` for completion and partial-success

        counts.


        `school_location_mappings` maps each `school_id` in the payload to a

        Coram location ID. Requires `write:*` scope and an `admin` creator role;

        the feature must be enabled for the organization.'
      tags:
      - reunification
      security:
      - X-Auth-Token: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReunificationImportInput'
      responses:
        '202':
          description: Import accepted and processing started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReunificationImportStatus'
        '400':
          description: Empty payload, missing school_location_mappings, or invalid data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthErrorResponse'
        '403':
          description: API key lacks the required scope/role, or the feature is not enabled for the organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthErrorResponse'
        '409':
          description: An import is already running for this organization; poll the existing one instead
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthErrorResponse'
        '500':
          description: Unexpected server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthErrorResponse'
      x-public-api: true
      x-public-api-version: v1
      parameters: []
  /v1/reunification/imports/status:
    get:
      operationId: get_reunification_import_status
      summary: Get the current reunification import status
      description: 'Returns the status of the organization''s most recent reunification

        import, including per-entity synced/total counts and the

        `succeeded_users` / `failed_users` provisioning figures. Poll this

        after starting an import. Requires `read:*` scope and a `regular`

        creator role.


        Note: `succeeded_users` and `failed_users` are eventually consistent.

        Guest/staff accounts are provisioned in the background after the roster

        is imported, so these counts keep climbing for a few seconds after

        `status` becomes `completed`. Treat `completed` as "roster imported" and

        keep polling the user counts until they stop changing.


        `completed` means the roster was imported and account provisioning was

        dispatched — it does **not** by itself mean every account succeeded.

        Check `failed_users`: a non-zero value on a `completed` import is a

        partial success (e.g. seat limits or Auth0 rejections for some users).'
      tags:
      - reunification
      security:
      - X-Auth-Token: []
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReunificationImportStatus'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthErrorResponse'
        '403':
          description: API key lacks the required scope/role, or the feature is not enabled for the organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthErrorResponse'
        '404':
          description: No import found for this organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthErrorResponse'
        '500':
          description: Unexpected server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthErrorResponse'
      x-public-api: true
      x-public-api-version: v1
      parameters: []
components:
  schemas:
    ReunificationTeacher:
      type: object
      required:
      - teacher_id
      - name
      - school_ids
      properties:
        teacher_id:
          type: string
        name:
          type: string
        sis_id:
          type: string
        email:
          type: string
        phone_number:
          type: string
        school_ids:
          type: array
          items:
            type: string
    ReunificationSchool:
      type: object
      required:
      - school_id
      - name
      properties:
        school_id:
          type: string
          description: Your identifier for the school; referenced by students/teachers/staff and school_location_mappings.
        name:
          type: string
        sis_id:
          type: string
        address:
          type: string
        city:
          type: string
        state:
          type: string
        zip:
          type: string
    AuthErrorResponse:
      type: object
      required:
      - detail
      properties:
        detail:
          type: string
          description: 'Human-readable error description. Matches the shape FastAPI uses

            for `HTTPException` responses, so existing code that parses the

            Python developer-api''s auth errors works unchanged.

            '
    ReunificationImportInput:
      type: object
      required:
      - schools
      - students
      - teachers
      - sections
      - school_location_mappings
      description: 'Full-replace roster payload. `schools`, `students`, `teachers`, and

        `sections` must be present (may be empty arrays) so an omitted key can''t

        silently delete that entity type; `staff` is optional. Phone numbers are

        normalized to E.164; a number that can''t be parsed for the region is

        dropped (stored as null), not rejected — so a malformed guardian

        contact number is silently lost rather than failing the import.

        '
      properties:
        schools:
          type: array
          items:
            $ref: '#/components/schemas/ReunificationSchool'
        students:
          type: array
          items:
            $ref: '#/components/schemas/ReunificationStudent'
        teachers:
          type: array
          items:
            $ref: '#/components/schemas/ReunificationTeacher'
        staff:
          type: array
          items:
            $ref: '#/components/schemas/ReunificationStaff'
        sections:
          type: array
          description: Class/section memberships that establish student↔teacher relationships.
          items:
            $ref: '#/components/schemas/ReunificationSection'
        school_location_mappings:
          type: object
          additionalProperties:
            type: integer
            format: int32
          description: Maps each school_id in the payload to a Coram location ID.
    ReunificationStaff:
      type: object
      required:
      - staff_id
      - name
      - school_ids
      properties:
        staff_id:
          type: string
        name:
          type: string
        sis_id:
          type: string
        email:
          type: string
        phone_number:
          type: string
        title:
          type: string
        department:
          type: string
        roles:
          type: array
          items:
            type: string
        school_ids:
          type: array
          items:
            type: string
    ReunificationSection:
      type: object
      required:
      - section_id
      description: A class/section linking students to teachers (drives student↔teacher relationships).
      properties:
        section_id:
          type: string
        school_id:
          type: string
        teacher_ids:
          type: array
          items:
            type: string
        student_ids:
          type: array
          items:
            type: string
    ReunificationStudent:
      type: object
      required:
      - student_id
      - name
      - school_ids
      properties:
        student_id:
          type: string
        name:
          type: string
        sis_id:
          type: string
        email:
          type: string
        phone_number:
          type: string
        grade:
          type: string
        school_ids:
          type: array
          description: School IDs the student belongs to. The first is the primary school; the rest are secondary.
          items:
            type: string
        guardians:
          type: array
          items:
            $ref: '#/components/schemas/ReunificationGuardian'
    ReunificationImportStatus:
      type: object
      required:
      - id
      - status
      description: 'Progress and partial-success report for a reunification import. Counts

        are cumulative for the current/most-recent import.

        '
      properties:
        id:
          type: string
        status:
          type: string
          enum:
          - in_progress
          - completed
          - failed
        synced_schools:
          type: integer
          format: int32
          default: 0
        total_schools:
          type: integer
          format: int32
          default: 0
        synced_students:
          type: integer
          format: int32
          default: 0
        total_students:
          type: integer
          format: int32
          default: 0
        synced_teachers:
          type: integer
          format: int32
          default: 0
        total_teachers:
          type: integer
          format: int32
          default: 0
        synced_staff:
          type: integer
          format: int32
          default: 0
        total_staff:
          type: integer
          format: int32
          default: 0
        synced_guardians:
          type: integer
          format: int32
          default: 0
        total_guardians:
          type: integer
          format: int32
          default: 0
        succeeded_users:
          type: integer
          format: int32
          default: 0
        failed_users:
          type: integer
          format: int32
          default: 0
        error_message:
          type: string
        started_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
    ReunificationGuardian:
      type: object
      required:
      - name
      properties:
        name:
          type: string
        email:
          type: string
        phone:
          type: string
        relationship:
          type: string
  securitySchemes:
    X-Auth-Token:
      type: apiKey
      in: header
      name: X-Auth-Token
x-tagGroups:
- name: Surveillance
  tags:
  - cameras
  - camera-groups
  - locations
  - nvrs
  - alerts
- name: Access Control
  tags:
  - doors
  - events
- name: Emergency Management System
  tags:
  - reunification