openapi: 3.1.3
info:
  x-logo:
    url: https://s3.amazonaws.com/cdn.skyslope.com/forms/forms-logo-w-top-padding.png
    href: https://skyslope.com/
    altText: SkySlope
  title: SkySlope Partnership API Reference Agents, Listings Users API
  version: 1.0.0
  description: "# Introduction\n  The SkySlope Forms API is organized around [REST](https://en.wikipedia.org/wiki/Representational_state_transfer).\n  Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses,\n  and uses standard HTTP response codes, authentication, and verbs.<br/><br/>\n  NOTE: Endpoints marked with an asterisk (*) will be available to our partners in the near future.\n  # Authentication\n  This API uses [OAuth 2.0 authorization code flow](https://www.oauth.com/oauth2-servers/server-side-apps/authorization-code/)\n  to obtain an access token that can be used to authenticate subsequent API requests.\n  ## Access Tokens\n  ### Request\n  To obtain an access token, first redirect the user to the authorization endpoint:\n  ```\n  https://accounts.skyslope.com/oauth2/authorize?\n    response_type=code\n    &client_id={YOUR_CLIENT_ID}\n    &redirect_uri={YOUR_REDIRECT_URI}\n    &scope=forms.files\n    &state={RANDOM_STATE_VALUE}\n    &code_challenge={CODE_CHALLENGE}\n    &code_challenge_method=S256\n  ```\n  After the user authorizes your application, they'll be redirected back to your redirect URI with an authorization code.\n  Exchange this code for an access token by making a POST request to the token endpoint:\n  ```\n  POST /oauth2/token HTTP/1.1\n  Host: accounts.skyslope.com\n  Content-Type: application/x-www-form-urlencoded\n  \n  grant_type=authorization_code\n  &client_id={YOUR_CLIENT_ID}\n  &client_secret={YOUR_CLIENT_SECRET}\n  &code={AUTHORIZATION_CODE}\n  &redirect_uri={YOUR_REDIRECT_URI}\n  &code_verifier={CODE_VERIFIER}\n  ```\n  ### Usage\n  Authentication to the API is performed by including your access token in the **Authorization** header of your\n  API requests with the Bearer authentication scheme:\n  ```\n  GET /partner/api/files HTTP/1.1\n  Host: forms.skyslope.com\n  Authorization: Bearer {YOUR_ACCESS_TOKEN}\n  ```\n  All API requests must be made over [HTTPS](https://en.wikipedia.org/wiki/HTTPS). Calls made over plain HTTP will fail.\n  API requests without authentication will also fail.\n  ## Refresh Tokens\n  Refresh tokens allow you to obtain new access tokens without requiring the user to re-authenticate. When you first\n  complete the OAuth flow, you'll receive both an access token and a refresh token.\n  ### Request\n  To receive a refresh token, include the `offline_access` scope in your initial authorization request:\n  ```\n  https://accounts.skyslope.com/oauth2/authorize?\n    response_type=code\n    &client_id={YOUR_CLIENT_ID}\n    &scope=forms.files offline_access\n    &redirect_uri={YOUR_REDIRECT_URI}\n  ```\n  ### Usage\n  When your access token expires, make a POST request to the token endpoint:\n  ```\n  POST /oauth2/token HTTP/1.1\n  Host: accounts.skyslope.com\n  Content-Type: application/x-www-form-urlencoded\n  \n  grant_type=refresh_token\n  &client_id={YOUR_CLIENT_ID}\n  &client_secret={YOUR_CLIENT_SECRET}\n  &refresh_token={YOUR_REFRESH_TOKEN}\n  ```\n  This will return a new access token and refresh token pair.\n  ### Security Best Practices\n  - Store refresh tokens securely on your backend server, never on client side\n  - Encrypt refresh tokens at rest using strong encryption\n  - Rotate refresh token on each use\n  - Set up monitoring for unusual refresh token usage patterns\n  - If a refresh token is compromised, revoke it immediately using the token revocation endpoint\n  - Implement automatic cleanup of unused refresh tokens"
  termsOfService: https://skyslope.com/terms-conditions/
  contact:
    name: Support
    url: https://support.skyslope.com/hc/en-us
    email: support@skyslope.com
servers:
- url: https://forms.skyslope.com/partner/api
  description: Production server
- url: https://staging-forms.skyslope.com/partner/api
  description: Staging server
- url: https://integ-forms.skyslope.com/partner/api
  description: Integration server
tags:
- name: Users
paths:
  /users/profile:
    get:
      summary: Get User Profile
      tags:
      - Users
      description: Retrieve the user profile of the currently authenticated user
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The id of the user who belongs to the profile.
                  subscriberId:
                    type: string
                    description: The subscriber id of the user.
                  firstName:
                    type: string
                    description: The first name of the user.
                  middleName:
                    type: string
                    description: The middle name of the user.
                  lastName:
                    type: string
                    description: The last name of the user.
                  suffix:
                    type: string
                    description: The suffix of the user.
                  email:
                    type: string
                    description: The email of the user.
                  primaryPhoneNumber:
                    type: string
                    description: The primary phone number of the user.
                  brokerageName:
                    type: string
                    description: The name of the brokerage that the user belongs to.
                  brokerageAddress:
                    type: object
                    description: The address of the brokerage that the user belongs to.
                    properties:
                      streetAddress:
                        type: string
                        description: The street address of the brokerage.
                      unitNumber:
                        type: string
                        description: The unit number of the brokerage.
                      city:
                        type: string
                        description: The city of the brokerage.
                      state:
                        type: string
                        description: The state of the brokerage.
                      postalCode:
                        type: string
                        description: The postal code of the brokerage.
                      county:
                        type: string
                        description: The county of the brokerage.
                  brokeragePhone:
                    type: string
                    description: The phone number of the brokerage that the user belongs to.
                  brokerageFax:
                    type: string
                    description: The fax number of the brokerage that the user belongs to.
                  regions:
                    type: array
                    description: An array of regions that the user has access to.
                    items:
                      type: object
                      properties:
                        country:
                          type: string
                        region:
                          type: string
                  libraries:
                    type: array
                    description: An array of libraries that the user has access to.
                    items:
                      type: number
                  authProfiles:
                    type: array
                    description: An array of the auth profiles of the user.
                    items:
                      additionalFields: true
                  isInitialized:
                    type: boolean
                    description: Evaluates to true if the user profile has been on-boarded.
                  termAcceptanceDate:
                    type: string
                    description: The date and time the user accepted the terms.
                  mlsCode:
                    type: string
                    description: The mls code of the user.
                  licenseNumber:
                    type: string
                    description: The license number of the user.
                  brokerageLicenseNumber:
                    type: string
                    description: The license number of the brokerage that the user belongs to.
                  brokerageMLSCode:
                    type: string
                    description: The mls code of the brokerage that the user belongs to.
                  isAutoDeletePreDraftEnvelopeAllowed:
                    type: boolean
                    description: Evaluates to true if auto delete pre draft envelopes is enabled.
                  isAutoDeleteFormAllowed:
                    type: boolean
                    description: Evaluates to true if auto delete forms is enabled.
                  consentedAssociations:
                    type: array
                    description: An array of the consented associations for the user.
                    items:
                      type: string
                  userPreferences:
                    type: object
                    properties:
                      digitalSigningPlatformPreference:
                        type: string
                        description: The digital signing platform preference of the user.
                      nhdProviderPreference:
                        type: string
                        description: The nhd provider preference of the user.
                  location:
                    type: string
                    description: The location of the user.
                  createdOn:
                    type: string
                    description: The date and time the user profile was created.
                  createdBy:
                    type: string
                    description: The id of the user who created the user profile.
                  updatedOn:
                    type: string
                    description: The date and time the user profile was last updated.
                  updatedBy:
                    type: string
                    description: The id of the user who last updated the user profile.
        default:
          description: An object containing the error that occurred.
          content:
            application/json:
              schema:
                type: object
                description: An object containing the error that occurred.
                properties:
                  code:
                    type: string
                    description: A code that represents the error that occurred.
                  message:
                    type: string
                    description: A description of the error that occurred.
                  errors:
                    type: array
                    description: An array of the errors that occurred.
                    items:
                      type: string
                  traceId:
                    type: string
                    description: A request correlation ID.
  /group:
    post:
      summary: Add Group
      tags:
      - Users
      description: 'Create a new group via accounts-api.<div style="color: rgba(38, 50, 56, 0.5); border-bottom: 1px solid rgba(38, 50, 56, 0.3); padding-bottom: 1px;">REQUIRED SCOPES:</div><div style="display: inline-flex; gap: 5px; padding: 5px;"><div style="border-radius: 2px; border: 1px solid rgba(128,128,255,0.5); background-color: rgba(64,64,255,0.25); padding: 0px 5px;">admin.groups</div></div>'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                brokerageId:
                  type: string
                  description: The brokerage id for the new group. If not provided, will be auto-generated with prefix "partnerApi_".
                brokerageName:
                  type: string
                  description: The name of the brokerage.
      responses:
        '200':
          description: Group already exists.
          content:
            application/json:
              schema:
                type: object
                properties:
                  groupId:
                    type: string
                    description: The id of the newly created group.
                required:
                - groupId
        '201':
          description: Group successfully created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  groupId:
                    type: string
                    description: The id of the newly created group.
                required:
                - groupId
        '400':
          description: An object containing the error that occurred.
          content:
            application/json:
              schema:
                type: object
                description: An object containing the error that occurred.
                properties:
                  code:
                    type: string
                    description: A code that represents the error that occurred.
                  message:
                    type: string
                    description: A description of the error that occurred.
                  errors:
                    type: array
                    description: An array of the errors that occurred.
                    items:
                      type: string
                  traceId:
                    type: string
                    description: A request correlation ID.
        '401':
          description: An object containing the error that occurred.
          content:
            application/json:
              schema:
                type: object
                description: An object containing the error that occurred.
                properties:
                  code:
                    type: string
                    description: A code that represents the error that occurred.
                  message:
                    type: string
                    description: A description of the error that occurred.
                  errors:
                    type: array
                    description: An array of the errors that occurred.
                    items:
                      type: string
                  traceId:
                    type: string
                    description: A request correlation ID.
        '500':
          description: An object containing the error that occurred.
          content:
            application/json:
              schema:
                type: object
                description: An object containing the error that occurred.
                properties:
                  code:
                    type: string
                    description: A code that represents the error that occurred.
                  message:
                    type: string
                    description: A description of the error that occurred.
                  errors:
                    type: array
                    description: An array of the errors that occurred.
                    items:
                      type: string
                  traceId:
                    type: string
                    description: A request correlation ID.
        default:
          description: An object containing the error that occurred.
          content:
            application/json:
              schema:
                type: object
                description: An object containing the error that occurred.
                properties:
                  code:
                    type: string
                    description: A code that represents the error that occurred.
                  message:
                    type: string
                    description: A description of the error that occurred.
                  errors:
                    type: array
                    description: An array of the errors that occurred.
                    items:
                      type: string
                  traceId:
                    type: string
                    description: A request correlation ID.
  /groups/{groupId}/child:
    post:
      summary: Add Child Group
      tags:
      - Users
      description: 'Create a new child group for a parent group via accounts-api.<div style="color: rgba(38, 50, 56, 0.5); border-bottom: 1px solid rgba(38, 50, 56, 0.3); padding-bottom: 1px;">REQUIRED SCOPES:</div><div style="display: inline-flex; gap: 5px; padding: 5px;"><div style="border-radius: 2px; border: 1px solid rgba(128,128,255,0.5); background-color: rgba(64,64,255,0.25); padding: 0px 5px;">admin.groups</div></div>'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  minLength: 1
                  description: The name of the child group.
        required: true
      parameters:
      - schema:
          type: string
          minLength: 1
        in: path
        name: groupId
        required: true
        description: The id of the parent group.
      responses:
        '200':
          description: Child group already exists for the parent group.
          content:
            application/json:
              schema:
                type: object
                properties:
                  childGroupId:
                    type: string
                    description: The id of the newly created child group.
                required:
                - childGroupId
        '201':
          description: Child group successfully created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  childGroupId:
                    type: string
                    description: The id of the newly created child group.
                required:
                - childGroupId
        '400':
          description: An object containing the error that occurred.
          content:
            application/json:
              schema:
                type: object
                description: An object containing the error that occurred.
                properties:
                  code:
                    type: string
                    description: A code that represents the error that occurred.
                  message:
                    type: string
                    description: A description of the error that occurred.
                  errors:
                    type: array
                    description: An array of the errors that occurred.
                    items:
                      type: string
                  traceId:
                    type: string
                    description: A request correlation ID.
        '401':
          description: An object containing the error that occurred.
          content:
            application/json:
              schema:
                type: object
                description: An object containing the error that occurred.
                properties:
                  code:
                    type: string
                    description: A code that represents the error that occurred.
                  message:
                    type: string
                    description: A description of the error that occurred.
                  errors:
                    type: array
                    description: An array of the errors that occurred.
                    items:
                      type: string
                  traceId:
                    type: string
                    description: A request correlation ID.
        '500':
          description: An object containing the error that occurred.
          content:
            application/json:
              schema:
                type: object
                description: An object containing the error that occurred.
                properties:
                  code:
                    type: string
                    description: A code that represents the error that occurred.
                  message:
                    type: string
                    description: A description of the error that occurred.
                  errors:
                    type: array
                    description: An array of the errors that occurred.
                    items:
                      type: string
                  traceId:
                    type: string
                    description: A request correlation ID.
        default:
          description: An object containing the error that occurred.
          content:
            application/json:
              schema:
                type: object
                description: An object containing the error that occurred.
                properties:
                  code:
                    type: string
                    description: A code that represents the error that occurred.
                  message:
                    type: string
                    description: A description of the error that occurred.
                  errors:
                    type: array
                    description: An array of the errors that occurred.
                    items:
                      type: string
                  traceId:
                    type: string
                    description: A request correlation ID.
  /users/{userId}/groups/{groupId}:
    post:
      summary: Add Group to User
      tags:
      - Users
      description: 'Add group to a user.<div style="color: rgba(38, 50, 56, 0.5); border-bottom: 1px solid rgba(38, 50, 56, 0.3); padding-bottom: 1px;">REQUIRED SCOPES:</div><div style="display: inline-flex; gap: 5px; padding: 5px;"><div style="border-radius: 2px; border: 1px solid rgba(128,128,255,0.5); background-color: rgba(64,64,255,0.25); padding: 0px 5px;">admin.groups</div></div>'
      parameters:
      - schema:
          type: string
          minLength: 1
        in: path
        name: userId
        required: true
        description: The id of the user to add to the group.
      - schema:
          type: string
          minLength: 1
        in: path
        name: groupId
        required: true
        description: The id of the group to add the user to.
      responses:
        '204':
          description: Group successfully added to user.
        default:
          description: An object containing the error that occurred.
          content:
            application/json:
              schema:
                type: object
                description: An object containing the error that occurred.
                properties:
                  code:
                    type: string
                    description: A code that represents the error that occurred.
                  message:
                    type: string
                    description: A description of the error that occurred.
                  errors:
                    type: array
                    description: An array of the errors that occurred.
                    items:
                      type: string
                  traceId:
                    type: string
                    description: A request correlation ID.
    delete:
      summary: Remove User from Group
      tags:
      - Users
      description: 'Remove a user from a group.<div style="color: rgba(38, 50, 56, 0.5); border-bottom: 1px solid rgba(38, 50, 56, 0.3); padding-bottom: 1px;">REQUIRED SCOPES:</div><div style="display: inline-flex; gap: 5px; padding: 5px;"><div style="border-radius: 2px; border: 1px solid rgba(128,128,255,0.5); background-color: rgba(64,64,255,0.25); padding: 0px 5px;">admin.groups</div></div>'
      parameters:
      - schema:
          type: string
          minLength: 1
        in: path
        name: userId
        required: true
        description: The id of the user to remove from the group.
      - schema:
          type: string
          minLength: 1
        in: path
        name: groupId
        required: true
        description: The id of the group to remove the user from.
      responses:
        '204':
          description: User successfully removed from group.
        default:
          description: An object containing the error that occurred.
          content:
            application/json:
              schema:
                type: object
                description: An object containing the error that occurred.
                properties:
                  code:
                    type: string
                    description: A code that represents the error that occurred.
                  message:
                    type: string
                    description: A description of the error that occurred.
                  errors:
                    type: array
                    description: An array of the errors that occurred.
                    items:
                      type: string
                  traceId:
                    type: string
                    description: A request correlation ID.