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

# Register

> Register new healthcare provider or link existing provider to partner organization

Use this endpoint to register a **new healthcare <Tooltip tip="A healthcare professional within an organization who uses Suki's services to document patient care." cta="View in Glossary" href="/Glossary/p">provider</Tooltip>** in the Suki platform or to link an **existing provider** to a new **<Tooltip tip="An organization that integrates with Suki's platform to offer AI-powered clinical documentation services to their users." cta="View in Glossary" href="/Glossary/p">Partner</Tooltip>**-organization relationship.

This is a **one-time** setup call for each provider within an organization.

## Registration scenarios

This endpoint handles **three** different scenarios depending on the user's status in the Suki system.

| Scenario                          | Condition                                                                 | Actions Taken                                                                                                                          | Response     |
| --------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| **New User**                      | The provider does not exist in Suki.                                      | • Creates a new organization<br />• Links your partner account to the organization<br />• Creates a new user with the provided details | 201 Created  |
| **Existing User, New Link**       | The provider exists but is not yet linked to your partner account.        | • Verifies the user and organization details<br />• Links your partner account to the existing organization                            | 201 Created  |
| **Existing User, Already Linked** | The provider and organization are already linked to your partner account. | • Detects the existing link                                                                                                            | 409 Conflict |

## Code examples

<Tabs>
  <Tab title="Python">
    ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    import requests

    url = "https://sdp.suki-stage.com/api/v1/auth/register"

    payload = {
        "partner_id": "your-partner-id",
        "partner_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
        "provider_name": "Dr. John Smith",
        "provider_org_id": "org-123",
        "provider_id": "provider-123",  # Optional
        "provider_specialty": "CARDIOLOGY"  # Optional, defaults to FAMILY_MEDICINE
    }

    response = requests.post(url, json=payload)

    if response.status_code == 201:
        print("Provider registered successfully")
    elif response.status_code == 409:
        print("Provider already linked to this partner")
    else:
        print(f"Registration failed: {response.status_code}")
        print(response.json())
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    const response = await fetch('https://sdp.suki-stage.com/api/v1/auth/register', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        partner_id: 'your-partner-id',
        partner_token: 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...',
        provider_name: 'Dr. John Smith',
        provider_org_id: 'org-123',
        provider_id: 'provider-123', // Optional
        provider_specialty: 'CARDIOLOGY' // Optional, defaults to FAMILY_MEDICINE
      })
    });

    if (response.status === 201) {
      console.log('Provider registered successfully');
    } else if (response.status === 409) {
      console.log('Provider already linked to this partner');
    } else {
      const error = await response.json();
      console.error(`Registration failed: ${response.status}`, error);
    }
    ```
  </Tab>
</Tabs>


## OpenAPI

````yaml POST /api/v1/auth/register
openapi: 3.0.1
info:
  title: Suki Developer Platform
  description: >-
    REST and WebSocket APIs for the Suki Developer Platform. Authenticate with
    Login or Register to obtain a Suki access token, then integrate ambient
    clinical documentation, form filling, transcription, and reference metadata
    endpoints.
  contact: {}
  version: '1.0'
servers:
  - url: https://sdp.suki.ai
    description: >-
      Production base URL for Suki Developer Platform REST APIs. WebSocket
      endpoints use the same host with `wss://`.
security:
  - SukiTokenAuth: []
paths:
  /api/v1/auth/register:
    post:
      tags:
        - /api/v1/auth
      summary: Register provider
      description: >-
        Registers a new provider in Suki or links an existing provider to your
        partner organization. This is a one-time setup call per provider.
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/controllers.RegistrationRequest'
        required: true
      responses:
        '201':
          description: Resource created successfully.
          content: {}
        '400':
          description: Bad request. The request body or parameters failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.BadRequestError'
        '401':
          description: Unauthorized. The Suki access token is missing, expired, or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.AuthenticationError'
        '403':
          description: Forbidden. The authenticated user cannot access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ForbiddenError'
        '404':
          description: Not found. The session, encounter, or resource ID does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.NotFoundError'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ConflictError'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.InternalServerError'
      security: []
components:
  schemas:
    controllers.RegistrationRequest:
      type: object
      required:
        - partner_id
        - partner_token
        - provider_name
        - provider_org_id
      properties:
        partner_id:
          type: string
          description: >-
            Unique identifier for the partner. This will be shared securely by
            Suki to the partner through a separate partner registration process.
          example: your-partner-id
        partner_token:
          type: string
          description: >-
            JWT token issued by trusted authorization server. The token must
            include Provider Email.
          example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
        provider_id:
          type: string
          description: >-
            **Optional** - Unique identifier for the provider. This is required
            for Bearer type partners only and will be ignored for other partner
            types. This must match a pre-defined expression.
          example: provider-123
        provider_name:
          type: string
          description: Name of the provider.
          example: Dr. John Smith
        provider_org_id:
          type: string
          description: Health system or organization to which the provider belongs.
          example: org-123
        provider_specialty:
          type: string
          description: >-
            **Optional** - Medical specialty of the provider. Defaults to
            FAMILY_MEDICINE if not provided.
          example: CARDIOLOGY
      description: Provider registration details and partner credentials from onboarding.
      example:
        partner_id: your-partner-id
        partner_token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
        provider_id: provider-123
        provider_name: Dr. John Smith
        provider_org_id: org-123
        provider_specialty: CARDIOLOGY
    controllers.BadRequestError:
      type: object
      properties:
        code:
          type: integer
          example: 400
          description: HTTP status code for the error.
        message:
          type: string
          example: invalid request
          description: Human-readable description of the validation or request error.
      description: Error response when the request fails validation.
    controllers.AuthenticationError:
      type: object
      properties:
        code:
          type: integer
          example: 401
          description: HTTP status code for the error.
        message:
          type: string
          example: invalid token
          description: Human-readable description of the authentication failure.
      description: Error response when authentication fails.
    controllers.ForbiddenError:
      type: object
      properties:
        code:
          type: integer
          example: 403
          description: HTTP status code for the error.
        message:
          type: string
          example: forbidden
          description: Human-readable description of the authorization failure.
      description: Error response when the caller lacks permission.
    controllers.NotFoundError:
      type: object
      properties:
        code:
          type: integer
          example: 404
          description: HTTP status code for the error.
        message:
          type: string
          example: not found
          description: Human-readable description of the missing resource.
      description: Error response when the requested resource was not found.
    controllers.ConflictError:
      type: object
      properties:
        code:
          type: integer
          example: 409
          description: HTTP status code for the error.
        message:
          type: string
          example: conflict
          description: Human-readable description of the conflict.
      description: Conflict Response
    controllers.InternalServerError:
      type: object
      properties:
        code:
          type: integer
          example: 500
          description: HTTP status code for the error.
        message:
          type: string
          example: internal server error
          description: Human-readable description of the server error.
      description: Error response when the server encounters an unexpected error.
  securitySchemes:
    SukiTokenAuth:
      type: apiKey
      in: header
      name: sdp_suki_token
      description: >-
        Suki access token for the authenticated provider. Obtain this by calling
        Login or Register with a valid `partner_token`. Pass the `suki_token`
        value from the JSON response as the `sdp_suki_token` header on REST
        requests and non-browser WebSocket upgrades. Browser WebSocket clients
        pass the token in `Sec-WebSocket-Protocol` instead. Tokens expire after
        one hour; call Login again to refresh.

````