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

# Create a branch

> Create a new branch for the authenticated institution. Only `name` is required; omitted fields use server defaults. The branch name must be unique within the institution — a duplicate returns 409. Once created, the branch can be referenced as `institutionalBranchName` when creating accounts.



## OpenAPI

````yaml /scribe-api/openapi-institutional.json post /v1/institutional/branches
openapi: 3.1.0
info:
  title: Scribe Public API
  description: >-
    External-facing REST API for integrating with the Telepatia platform.
    Authenticate with API keys, set consultation context, and look up scribe
    sessions.
  version: 0.1.0
servers:
  - url: https://scribe-api.telepatia.ai
    description: Production
security:
  - BearerAuth: []
paths:
  /v1/institutional/branches:
    post:
      tags:
        - Institutional
        - Institutional
      summary: Create a branch
      description: >-
        Create a new branch for the authenticated institution. Only `name` is
        required; omitted fields use server defaults. The branch name must be
        unique within the institution — a duplicate returns 409. Once created,
        the branch can be referenced as `institutionalBranchName` when creating
        accounts.
      operationId: api_institutional_branch_created_v1_institutional_branches_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBranchRequest'
            example:
              address: 'Av. 7 #12-34'
              main: false
              name: Sede Norte
              type: single
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateBranchResponse'
        '400':
          description: >-
            Bad Request — invalid parameters, validation failures, or missing
            fields.
          content:
            application/json:
              examples:
                parameter_missing:
                  summary: Missing required field
                  value:
                    error:
                      type: invalid_request_error
                      code: parameter_missing
                      message: name is required.
                      param: name
                parameter_invalid:
                  summary: Invalid field value
                  value:
                    error:
                      type: invalid_request_error
                      code: parameter_invalid
                      message: >-
                        idCountry must be a valid country name, ISO alpha-2, or
                        ISO alpha-3 code.
                      param: idCountry
                account_invalid:
                  summary: Invalid account
                  value:
                    error:
                      type: invalid_request_error
                      code: account_invalid
                      message: Account has no valid authId.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
          content:
            application/json:
              examples:
                authentication_required:
                  summary: Invalid or missing API key
                  value:
                    error:
                      type: authentication_error
                      code: authentication_required
                      message: Invalid API key.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict — resource already exists or is in a conflicting state.
          content:
            application/json:
              examples:
                resource_conflict:
                  summary: Resource conflict
                  value:
                    error:
                      type: invalid_request_error
                      code: resource_conflict
                      message: >-
                        consultationInternalId is already in use by a different
                        consultation.
                      param: consultationInternalId
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service Unavailable — an external dependency is down.
          content:
            application/json:
              examples:
                service_unavailable:
                  summary: External service unavailable
                  value:
                    error:
                      type: api_error
                      code: service_unavailable
                      message: >-
                        Unable to generate verification code. Please try again
                        later.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
components:
  schemas:
    CreateBranchRequest:
      properties:
        name:
          type: string
          maxLength: 255
          title: Name
          examples:
            - Sede Norte
        type:
          anyOf:
            - $ref: '#/components/schemas/InstitutionalBranchType'
            - type: 'null'
          examples:
            - single
        visible:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Visible
          examples:
            - true
        main:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Main
          examples:
            - false
        order:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Order
          examples:
            - 0
        description:
          anyOf:
            - type: string
              maxLength: 1000
            - type: 'null'
          title: Description
        address:
          anyOf:
            - type: string
              maxLength: 500
            - type: 'null'
          title: Address
          examples:
            - 'Av. 7 #12-34'
        IPS:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Ips
        coordinates:
          anyOf:
            - $ref: '#/components/schemas/Coordinates'
            - type: 'null'
        expectedConsultations:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Expectedconsultations
        branchManagerAccountIds:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Branchmanageraccountids
        cdssConfigurationId:
          anyOf:
            - type: string
            - type: 'null'
          title: Cdssconfigurationid
        auditConfigurationId:
          anyOf:
            - type: string
            - type: 'null'
          title: Auditconfigurationid
        sessionStartLabel:
          anyOf:
            - $ref: '#/components/schemas/SessionStartLabel'
            - type: 'null'
      type: object
      required:
        - name
      title: CreateBranchRequest
      description: >-
        Request body for creating an institution branch.


        Mirrors datalayer's branch input. Only ``name`` is required; omitted
        fields

        fall back to datalayer defaults (``visible=true``, ``type=single``,

        ``main=false``, ``order=0``, ``IPS=[]``). The branch ``id`` is generated

        server-side.
      examples:
        - address: 'Av. 7 #12-34'
          main: false
          name: Sede Norte
          type: single
    CreateBranchResponse:
      properties:
        id:
          type: string
          title: Id
          description: Server-generated branch id.
        name:
          type: string
          title: Name
          examples:
            - Sede Norte
        type:
          anyOf:
            - type: string
            - type: 'null'
          title: Type
          examples:
            - single
        visible:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Visible
        main:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Main
        order:
          anyOf:
            - type: integer
            - type: 'null'
          title: Order
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        address:
          anyOf:
            - type: string
            - type: 'null'
          title: Address
        IPS:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Ips
        coordinates:
          anyOf:
            - $ref: '#/components/schemas/Coordinates'
            - type: 'null'
        expectedConsultations:
          anyOf:
            - type: integer
            - type: 'null'
          title: Expectedconsultations
        branchManagerAccountIds:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Branchmanageraccountids
        cdssConfigurationId:
          anyOf:
            - type: string
            - type: 'null'
          title: Cdssconfigurationid
        auditConfigurationId:
          anyOf:
            - type: string
            - type: 'null'
          title: Auditconfigurationid
        sessionStartLabel:
          anyOf:
            - type: string
            - type: 'null'
          title: Sessionstartlabel
      type: object
      required:
        - id
        - name
      title: CreateBranchResponse
      description: Response body after creating an institution branch.
      examples:
        - address: 'Av. 7 #12-34'
          id: b1f2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d
          main: false
          name: Sede Norte
          order: 0
          type: single
          visible: true
    ErrorResponse:
      description: Standardized error response envelope.
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
      required:
        - error
      title: ErrorResponse
      type: object
    InstitutionalBranchType:
      type: string
      enum:
        - single
        - multi
      title: InstitutionalBranchType
      description: Branch type — single site or multi-site.
    Coordinates:
      properties:
        latitude:
          type: number
          maximum: 90
          minimum: -90
          title: Latitude
          examples:
            - 4.711
        longitude:
          type: number
          maximum: 180
          minimum: -180
          title: Longitude
          examples:
            - -74.072
      type: object
      required:
        - latitude
        - longitude
      title: Coordinates
      description: Geographic coordinates of a branch.
    SessionStartLabel:
      type: string
      enum:
        - consultation
        - reading
      title: SessionStartLabel
      description: Wording the scribe clients use on the start-session button.
    ErrorDetail:
      description: Error detail with machine-readable codes and human-readable message.
      properties:
        type:
          description: Broad error category for high-level handling.
          examples:
            - invalid_request_error
          title: Type
          type: string
        code:
          description: Machine-readable error code. Clients should switch on this value.
          examples:
            - parameter_invalid
          title: Code
          type: string
        message:
          description: Human-readable error message ending with a period.
          examples:
            - >-
              idCountry must be a valid country name, ISO alpha-2, or ISO
              alpha-3 code.
          title: Message
          type: string
        param:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: The request field that caused the error, if applicable.
          examples:
            - idCountry
          title: Param
        details:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          default: null
          description: Optional structured, machine-readable context for the error.
          examples:
            - pendingConsultations:
                - sessionId: abc123
                  url: https://...
          title: Details
      required:
        - type
        - code
        - message
      title: ErrorDetail
      type: object
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API key passed as a Bearer token

````