openapi: 3.2.0
info:
  title: Starlink Public Contacts API
  description: '<h3>Description</h3>API to manage Starlink accounts and devices. For interactive endpoints list see: <a href=''https://starlink.readme.io/''>https://starlink.readme.io/</a><h3>Authentication - OIDC</h3><p>To authenticate with this API using OIDC, <a target=''_blank'' href=''/api/auth/.well-known/openid-configuration''>Well Known URL</a> and attach the result to your requests with the <strong>Authorize</strong> button below.</p>'
  version: '2'
servers:
- url: /api
tags:
- name: Contacts
paths:
  /public/v2/contacts:
    get:
      tags:
      - Contacts
      summary: Get contacts
      description: 'Required permission: User management, Edit.<br/>Get list of contacts on the authenticated user''s account.'
      parameters:
      - name: page
        in: query
        description: Page of contacts to query.
        schema:
          type: integer
          format: int32
          default: 0
      responses:
        '400':
          description: Bad request. Invalid or missing parameter
        '401':
          description: Unauthorized
        '200':
          description: Contacts retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponsePaginatedServiceResponse'
        '422':
          description: Failed to retrieve contacts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceResponse'
        default:
          description: Error
        '403':
          description: user_lacks_required_permission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserLacksRequiredPermissionServiceResponse'
    post:
      tags:
      - Contacts
      summary: Create contact
      description: 'Required permission: Admin Only - API User Management, Edit.<br/>Creates the contact if it is new, and adds the contact to the authenticated account.'
      requestBody:
        description: Contact information to be added to account.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateContactOnAccountRequest'
      responses:
        '401':
          description: Unauthorized
        '400':
          description: Bad request. Invalid or missing parameter
        '200':
          description: Contact has been created and added to the account with the requested roles.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponseServiceResponse'
        '422':
          description: Failed to create the contact and add it to the account with the correct roles.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceResponse'
        '403':
          description: user_lacks_required_permission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserLacksRequiredPermissionServiceResponse'
  /public/v2/contacts/{subjectId}:
    delete:
      tags:
      - Contacts
      summary: Delete contact
      description: 'Required permission: Admin Only - API User Management, Edit.<br/>Deletes contact based on specified subject Id on the authenticated account.'
      parameters:
      - name: subjectId
        in: path
        description: Subject ID of contact to be deleted.
        required: true
        schema:
          type: string
      responses:
        '400':
          description: Bad request. Invalid or missing parameter
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '200':
          description: Contact successfully deleted from account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceResponse'
        '422':
          description: Failed to delete contact.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceResponse'
        default:
          description: Error
    put:
      tags:
      - Contacts
      summary: Update contact
      description: 'Required permission: Admin Only - API User Management, Edit.<br/>Update contact on the authenticated account.'
      parameters:
      - name: subjectId
        in: path
        description: Subject Id of the contact to be updated.
        required: true
        schema:
          type: string
      requestBody:
        description: Updates for contact.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateContactOnAccountRequest'
      responses:
        '400':
          description: Bad request. Invalid or missing parameter
        '401':
          description: Unauthorized
        '200':
          description: Updated contact.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponseServiceResponse'
        '422':
          description: Failed to update contact.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceResponse'
        default:
          description: Error
        '403':
          description: user_lacks_required_permission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserLacksRequiredPermissionServiceResponse'
components:
  schemas:
    ServiceResponse:
      type: object
      properties:
        errors:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ValidationResult'
          readOnly: true
        warnings:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ValidationResult'
          readOnly: true
        information:
          type:
          - array
          - 'null'
          items:
            type: string
          readOnly: true
        isValid:
          type: boolean
          readOnly: true
      additionalProperties: false
    UserResponsePaginatedServiceResponse:
      type: object
      properties:
        errors:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ValidationResult'
          readOnly: true
        warnings:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ValidationResult'
          readOnly: true
        information:
          type:
          - array
          - 'null'
          items:
            type: string
          readOnly: true
        isValid:
          type: boolean
          readOnly: true
        content:
          $ref: '#/components/schemas/UserResponsePaginated'
      additionalProperties: false
    UserLacksRequiredPermissionServiceResponse:
      type: object
      properties:
        errors:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ValidationResult'
          readOnly: true
        warnings:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ValidationResult'
          readOnly: true
        information:
          type:
          - array
          - 'null'
          items:
            type: string
          readOnly: true
        isValid:
          type: boolean
          readOnly: true
        content:
          $ref: '#/components/schemas/UserLacksRequiredPermission'
      additionalProperties: false
    UserResponseServiceResponse:
      type: object
      properties:
        errors:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ValidationResult'
          readOnly: true
        warnings:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ValidationResult'
          readOnly: true
        information:
          type:
          - array
          - 'null'
          items:
            type: string
          readOnly: true
        isValid:
          type: boolean
          readOnly: true
        content:
          $ref: '#/components/schemas/UserResponse'
      additionalProperties: false
    UserResponsePaginated:
      type: object
      properties:
        pageIndex:
          type: integer
          format: int32
        limit:
          type: integer
          format: int32
        isLastPage:
          type: boolean
        results:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/UserResponse'
        totalCount:
          type: integer
          format: int32
      additionalProperties: false
    ValidationResult:
      type: object
      properties:
        memberNames:
          type:
          - array
          - 'null'
          items:
            type: string
          readOnly: true
        errorMessage:
          type:
          - string
          - 'null'
      additionalProperties: false
    UserLacksRequiredPermission:
      type: object
      properties:
        accountId:
          type:
          - string
          - 'null'
        requiredPermission:
          $ref: '#/components/schemas/FeaturePermission'
        featureAccessString:
          type:
          - string
          - 'null'
        permissionString:
          type:
          - string
          - 'null'
      additionalProperties: false
    Permission:
      enum:
      - 0
      - 1
      type: integer
      format: int32
      x-enumNames:
      - View
      - Edit
    UserResponse:
      required:
      - email
      - roles
      - subjectId
      type: object
      properties:
        subjectId:
          minLength: 1
          type: string
          description: Unique subject ID given to this user.
        email:
          minLength: 1
          type: string
          description: User email.
        roles:
          type: array
          items:
            type: string
          description: List of User roles which map to permissions on the specified account.
      additionalProperties: false
    CreateContactOnAccountRequest:
      required:
      - email
      - firstName
      - lastName
      - locale
      - phoneNumber
      - roles
      type: object
      properties:
        firstName:
          minLength: 1
          type: string
          description: Contact first name.
        lastName:
          minLength: 1
          type: string
          description: Contact last name.
        roles:
          type: array
          items:
            type: string
          description: Contact roles on account.
        email:
          minLength: 1
          type: string
          description: Contact email.
        phoneNumber:
          minLength: 1
          type: string
          description: Contact phone number.
        locale:
          minLength: 1
          type: string
          description: Contact locale.
      additionalProperties: false
    FeatureAccess:
      enum:
      - 1
      - 2
      - 3
      - 4
      - 5
      - 6
      - 7
      - 8
      - 9
      - 10
      - 11
      - 12
      - 13
      - 14
      - 15
      - 16
      - 17
      - 18
      - 19
      - 20
      - 21
      - 22
      - 23
      - 3001
      - 3002
      - 3003
      type: integer
      format: int32
      x-enumNames:
      - DeviceTelemetry
      - DeviceCommand
      - Financial
      - UserManagement
      - AccountInformation
      - OutageHistory
      - SupportRequest
      - DeviceManagement
      - ServicePlan
      - UserViewership
      - ServiceAccountManagement
      - DataSharingPreferenceManagement
      - DeviceConfigurationAssignment
      - AviationFlightStatusManagement
      - AdminOnlyUserManagementViaAPI
      - ManagedAccountCreation
      - ManagedAccountsInventoryManagement
      - ManagedAccountInformation
      - ManagedAccountStructureManagement
      - ManagedAccountDeletion
      - ManagedAccountLocationSettings
      - DataUsageNotifications
      - ManagedAccountBillingInformation
      - GatedFeature__Installer
      - GatedFeature__LawEnforcementAgency
      - GatedFeature__StarlinkMobileData
    FeaturePermission:
      required:
      - featureAccess
      - permission
      type: object
      properties:
        featureAccess:
          $ref: '#/components/schemas/FeatureAccess'
        permission:
          $ref: '#/components/schemas/Permission'
      additionalProperties: false
    UpdateContactOnAccountRequest:
      type: object
      properties:
        roles:
          type:
          - array
          - 'null'
          items:
            type: string
          description: Contact roles on the account.
        phoneNumber:
          type:
          - string
          - 'null'
          description: Contact phone number.
      additionalProperties: false