> ## Documentation Index
> Fetch the complete documentation index at: https://docs.timeback.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upsert a user

> Creates or updates a user by their sourcedId



## OpenAPI

````yaml /openapi/learn-with-ai/platform-api.yaml put /rostering/1.0/users/{sourcedId}
openapi: 3.1.1
info:
  title: TimeBack Platform API
  description: >-
    RESTful API for the TimeBack Platform. Covers authentication, rostering,
    curriculum, insights, assessments, content grading, and more.
  version: 2026.09.10.1
servers:
  - url: https://platform.dev.timeback.com
    description: integration
security: []
tags:
  - name: Auth
    description: Authentication and authorization endpoints
  - name: Organizations
    description: Organizations module contains all endpoints around organization management
  - name: Applications
    description: Applications module contains all endpoints for managing LTI applications
  - name: Users
    description: >-
      Users module contains all endpoints around user creation, update and
      consultation
  - name: Students
    description: Students module contains all endpoints around student management
  - name: Demographics
    description: >-
      Demographics module contains all endpoints around demographics
      consultation
  - name: Consent
    description: >-
      Initiate and query TimeBack parental consent for a student, backed by an
      immutable audit trail.
  - name: Classes
    description: Classes module contains all endpoints around class management
  - name: Courses
    description: Courses module contains all endpoints around course management
  - name: Enrollments
    description: Enrollments module contains all endpoints around enrollment consultation
  - name: CASE
    description: Competency and Academic Standards Exchange (CASE) 1.1 API
  - name: Curriculum
    description: Curriculum module contains endpoints for managing curriculum data
  - name: Competency Track
    description: Competency track endpoints
  - name: Content Grading
    description: >-
      Registration and management of graders for free-response content items —
      bring-your-own external graders (Tier 2) and, once shipped,
      platform-managed grading prompts (Tier 1).
  - name: Caliper
    description: The Caliper module contains all endpoints around Caliper Analytics
  - name: Insights
    description: Coaching insights and session analytics endpoints
paths:
  /rostering/1.0/users/{sourcedId}:
    put:
      tags:
        - Users
      summary: Upsert a user
      description: Creates or updates a user by their sourcedId
      operationId: upsertUser
      parameters:
        - name: sourcedId
          in: path
          description: User ID
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        description: User object to be created or updated
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OneRosterUserInput'
      responses:
        '201':
          description: Successfully created or updated
        '400':
          $ref: '#/components/responses/BadRequest17'
        '500':
          $ref: '#/components/responses/InternalError16'
      security:
        - CognitoUserPoolAuthorizer:
            - https://purl.imsglobal.org/spec/or/v1p2/scope/roster.createput
components:
  schemas:
    OneRosterUserInput:
      type: object
      description: User information to be created or updated
      properties:
        user:
          type: object
          required:
            - sourcedId
            - status
            - enabledUser
            - givenName
            - familyName
            - primaryOrg
            - email
            - grades
          properties:
            sourcedId:
              type: string
              format: uuid
              description: Unique identifier for the user
            status:
              type: string
              enum:
                - active
                - tobedeleted
                - inactive
              description: Status of the user record
            metadata:
              type:
                - object
                - 'null'
              additionalProperties: true
              description: Additional metadata for the user
            userMasterIdentifier:
              type:
                - string
                - 'null'
              description: Master identifier for the user
            username:
              type:
                - string
                - 'null'
              description: Username for the user
            userIds:
              type:
                - array
                - 'null'
              description: External identifiers, e.g. SIS IDs.
              items:
                $ref: '#/components/schemas/OneRosterUserId'
            enabledUser:
              type: string
              enum:
                - 'true'
                - 'false'
              description: Whether the user account is enabled
            givenName:
              type: string
              description: User's first name
            familyName:
              type: string
              description: User's last name
            middleName:
              type:
                - string
                - 'null'
              description: User's middle name
            preferredFirstName:
              type:
                - string
                - 'null'
              description: User's preferred first name
            preferredMiddleName:
              type:
                - string
                - 'null'
              description: User's preferred middle name
            preferredLastName:
              type:
                - string
                - 'null'
              description: User's preferred last name
            pronouns:
              type:
                - string
                - 'null'
              description: User's preferred pronouns
            demographics:
              type: object
              description: Demographic information for the user
              properties:
                birthDate:
                  type:
                    - string
                    - 'null'
                  format: date
                  description: User's birth date
            primaryOrg:
              type: object
              required:
                - sourcedId
                - type
              properties:
                href:
                  type: string
                  description: URI reference to the organization
                sourcedId:
                  type: string
                  format: uuid
                  description: Organization ID
                type:
                  type: string
                  enum:
                    - org
                  description: Reference type
            identifier:
              type:
                - string
                - 'null'
              description: Additional identifier for the user
            email:
              type: string
              format: email
              description: User's email address
            sms:
              type:
                - string
                - 'null'
              description: User's SMS number
            phone:
              type:
                - string
                - 'null'
              description: User's phone number
            grades:
              type: array
              items:
                type: string
              description: Grade levels for the user
            password:
              type:
                - string
                - 'null'
              description: User's password
            roles:
              type: array
              description: Roles to be assigned to the user
              items:
                type: object
                required:
                  - roleType
                  - role
                  - org
                properties:
                  roleType:
                    type: string
                    enum:
                      - primary
                      - secondary
                  role:
                    type: string
                    enum:
                      - aide
                      - counselor
                      - districtAdministrator
                      - guardian
                      - parent
                      - principal
                      - proctor
                      - relative
                      - siteAdministrator
                      - student
                      - systemAdministrator
                      - teacher
                  org:
                    type: object
                    required:
                      - sourcedId
                      - type
                    properties:
                      href:
                        type: string
                      sourcedId:
                        type: string
                        format: uuid
                      type:
                        type: string
                        enum:
                          - org
      required:
        - user
    OneRosterUserId:
      type: object
      description: External identifier reference for a user (e.g., SIS ID).
      properties:
        type:
          type: string
          description: Type of the external identifier.
        identifier:
          type: string
          description: The external identifier value.
      required:
        - type
        - identifier
      additionalProperties: false
    imsxStatusInfoDType11:
      description: >
        This is the container for the status code and associated information
        returned within the HTTP messages received from the Service Provider.
        For the OneRoster Rostering service this object will only be returned to
        provide information about a failed request i.e. it will NOT be in the
        payload for a successful request.
      type: object
      required:
        - imsx_codeMajor
        - imsx_severity
      properties:
        imsx_codeMajor:
          description: |
            The code major value (from the corresponding enumerated vocabulary).
          type: string
          enum:
            - success
            - processing
            - failure
            - unsupported
        imsx_severity:
          description: |
            The severity value (from the corresponding enumerated vocabulary).
          type: string
          enum:
            - status
            - warning
            - error
        imsx_description:
          description: >-
            A human readable description supplied by the entity creating the
            status code information.
          type: string
        imsx_CodeMinor:
          $ref: '#/components/schemas/imsxCodeMinorDType11'
      additionalProperties: false
    imsxCodeMinorDType11:
      description: >
        This is the container for the set of code minor status codes reported in
        the responses from the Service Provider.
      type: object
      required:
        - imsx_codeMinorField
      properties:
        imsx_codeMinorField:
          description: |
            Each reported code minor status code.
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/imsxCodeMinorFieldDType11'
      additionalProperties: false
    imsxCodeMinorFieldDType11:
      description: |
        This is the container for a single code minor status code.
      type: object
      required:
        - imsx_codeMinorFieldName
        - imsx_codeMinorFieldValue
      properties:
        imsx_codeMinorFieldName:
          description: >-
            This should contain the identity of the system that has produced the
            code minor status code report. In most cases this will be the target
            service provider denoted as 'TargetEndSystem'.
          type: string
          default: TargetEndSystem
        imsx_codeMinorFieldValue:
          description: >
            The code minor status code (this is a value from the corresponding
            enumerated vocabulary).
          type: string
          enum:
            - fullsuccess
            - invalid_filter_field
            - invalid_selection_field
            - invaliddata
            - unauthorisedrequest
            - forbidden
            - server_busy
            - unknownobject
            - internal_server_error
      additionalProperties: false
  responses:
    BadRequest17:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/imsxStatusInfoDType11'
          examples:
            invalidData:
              value:
                imsx_codeMajor: failure
                imsx_severity: error
                imsx_description: Invalid data provided
                imsx_CodeMinor:
                  imsx_codeMinorField:
                    - imsx_codeMinorFieldName: TargetEndSystem
                      imsx_codeMinorFieldValue: invaliddata
            invalidFilter:
              value:
                imsx_codeMajor: failure
                imsx_severity: error
                imsx_description: Invalid filter field
                imsx_CodeMinor:
                  imsx_codeMinorField:
                    - imsx_codeMinorFieldName: TargetEndSystem
                      imsx_codeMinorFieldValue: invalid_filter_field
    InternalError16:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/imsxStatusInfoDType11'
          examples:
            default:
              value:
                imsx_codeMajor: failure
                imsx_severity: error
                imsx_description: Internal server error
                imsx_CodeMinor:
                  imsx_codeMinorField:
                    - imsx_codeMinorFieldName: TargetEndSystem
                      imsx_codeMinorFieldValue: internal_server_error
  securitySchemes:
    CognitoUserPoolAuthorizer:
      type: oauth2
      description: >-
        OAuth 2.0 client credentials flow. Contact timeback@trilogy.com to
        request credentials for your application.
      flows:
        clientCredentials:
          tokenUrl: https://platform.dev.timeback.com/auth/1.0/token
          scopes:
            https://purl.imsglobal.org/spec/or/v1p2/scope/roster.readonly: roster readonly
            https://purl.imsglobal.org/spec/or/v1p2/scope/roster-core.readonly: roster-core readonly
            https://purl.imsglobal.org/spec/or/v1p2/scope/roster.createput: roster createput
            https://purl.imsglobal.org/spec/lti/v1p3/scope/lti.readonly: lti readonly
            https://purl.imsglobal.org/spec/or/v1p2/scope/roster-demographics.readonly: roster-demographics readonly
            https://timeback-platform.trilogy.com/consent/scope/consent.write: consent write
            https://timeback-platform.trilogy.com/consent/scope/consent.read: consent read
            https://purl.imsglobal.org/spec/or/v1p2/scope/roster-core.createput: roster-core createput
            https://purl.imsglobal.org/spec/or/v1p2/scope/roster.delete: roster delete
            https://purl.imsglobal.org/spec/or/v1p2/scope/roster-core.delete: roster-core delete
            https://purl.imsglobal.org/spec/case/v1p0/scope/case.readonly: case readonly
            https://purl.imsglobal.org/spec/case/v1p0/scope/case.createput: case createput
            https://purl.imsglobal.org/spec/case/v1p0/scope/case.delete: case delete
            https://timeback-platform.trilogy.com/competency-track/scope/competency-track.readonly: competency-track readonly
            https://timeback-platform.trilogy.com/competency-track/scope/competency-track.write: competency-track write
            https://timeback-platform.trilogy.com/competency-track/scope/competency-track.delete: competency-track delete
            https://timeback-platform.trilogy.com/content/scope/content.write: content write
            https://timeback-platform.trilogy.com/content/scope/content.read: content read
            https://purl.imsglobal.org/spec/caliper/v1p2/scope/events.write: events write
            https://purl.imsglobal.org/spec/caliper/v1p2/scope/events.readonly: events readonly
            https://timeback-platform.trilogy.com/webhooks/scope/webhooks.write: webhooks write
            https://timeback-platform.trilogy.com/webhooks/scope/webhooks.read: webhooks read
            https://timeback-platform.trilogy.com/webhooks/scope/webhooks.delete: webhooks delete

````