openapi: 3.2.0
info:
  title: Subscription Custom Fields API
  version: 1.0.4
  description: '#### Copyright

    © Aeris Communications, Inc.'
  x-api-id: c866057a-0e0d-4409-87f6-62289b4d363e
  x-audience: external-partner
servers:
- url: https://iot-api.aeris.com/iot/api/subscriptions
  description: API server
tags:
- name: Subscription Custom Fields
  description: 'Custom fields are user-defined key-value pairs. They can be used for

    advanced filtering capabilities on single subscriptions as well as batch

    jobs. Custom fields can be created, modified and attached to

    subscriptions using this api.'
paths:
  /custom-fields:
    post:
      tags:
      - Subscription Custom Fields
      summary: Create a custom field (key)
      description: Create a new custom field
      operationId: create-custom-field
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomField'
      responses:
        '201':
          description: Custom field created
          allOf:
          - $ref: '#/components/responses/RateLimitedResponse'
        '400':
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                problem-response-example:
                  value:
                  - type: about:blank
                    title: Bad Request
                    status: 400
                    detail: organization already has maximum number of fields
                    instance: null
        '403':
          $ref: '#/components/responses/Response_403'
        '429':
          $ref: '#/components/responses/Response_429'
        '500':
          $ref: '#/components/responses/Response_500'
        default:
          $ref: '#/components/responses/Response_500'
      security:
      - Oauth2_auth:
        - custom-field.write
    get:
      tags:
      - Subscription Custom Fields
      summary: Get custom fields
      operationId: get-custom-fields
      responses:
        '200':
          description: 'OK.

            '
          allOf:
          - $ref: '#/components/responses/RateLimitedResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldsResponse'
              examples:
                get-custom-fields-response-example:
                  value:
                    items:
                    - id: 61
                      companyId: 85000018
                      organizationId: 3.85.3.18
                      fieldName: Test name
                      type: FREE_TEXT
        '403':
          $ref: '#/components/responses/Response_403'
        '429':
          $ref: '#/components/responses/Response_429'
        '500':
          $ref: '#/components/responses/Response_500'
        default:
          $ref: '#/components/responses/Response_500'
      security:
      - Oauth2_auth:
        - custom-field.read
  /custom-fields/{id}:
    put:
      tags:
      - Subscription Custom Fields
      summary: Update custom field predefined values
      description: Update existing custom field.
      operationId: update-custom-field
      parameters:
      - name: id
        in: path
        schema:
          type: string
          example: '123456789'
        required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomField'
      responses:
        '200':
          description: OK
          allOf:
          - $ref: '#/components/responses/RateLimitedResponse'
        '400':
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                bad-request-response-example:
                  value:
                  - type: about:blank
                    title: Bad Request
                    status: 400
                    detail: name is not allowed
                    instance: null
        '403':
          $ref: '#/components/responses/Response_403'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                not-found-response-example:
                  value:
                  - type: about:blank
                    title: Not Found
                    status: 404
                    detail: 'field not found: xyz'
                    instance: null
        '429':
          $ref: '#/components/responses/Response_429'
        '500':
          $ref: '#/components/responses/Response_500'
        default:
          $ref: '#/components/responses/Response_500'
      security:
      - Oauth2_auth:
        - custom-field.write
    delete:
      tags:
      - Subscription Custom Fields
      summary: Delete a custom field
      description: Delete a custom field.
      operationId: delete-custom-field
      parameters:
      - name: id
        in: path
        schema:
          type: string
          example: '123456789'
        required: true
      responses:
        '200':
          description: 'OK.

            '
          allOf:
          - $ref: '#/components/responses/RateLimitedResponse'
        '403':
          $ref: '#/components/responses/Response_403'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                not-found-response-example:
                  value:
                  - type: about:blank
                    title: Not Found
                    status: 404
                    detail: 'field not found: xyz'
                    instance: null
        '429':
          $ref: '#/components/responses/Response_429'
        '500':
          $ref: '#/components/responses/Response_500'
        default:
          $ref: '#/components/responses/Response_500'
      security:
      - Oauth2_auth:
        - custom-field.write
  /custom-fields/requests:
    post:
      tags:
      - Subscription Custom Fields
      summary: Add or update custom field value for subscription
      description: Create a subscription custom field update request for updating multiple subscriptions with one request.
      operationId: request-custom-field-update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCustomFieldRequest'
      responses:
        '201':
          description: 'Created, Location header will contain the created request url

            '
          allOf:
          - $ref: '#/components/responses/RateLimitedResponse'
        '400':
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                bad-request-response-example:
                  value:
                  - type: about:blank
                    title: Bad Request
                    status: 400
                    detail: no identifiers provided
                    instance: null
        '403':
          $ref: '#/components/responses/Response_403'
        '429':
          $ref: '#/components/responses/Response_429'
        '500':
          $ref: '#/components/responses/Response_500'
        default:
          $ref: '#/components/responses/Response_500'
      security:
      - Oauth2_auth:
        - subscription.write
components:
  schemas:
    SubscriptionCustomFields:
      type: array
      items:
        $ref: '#/components/schemas/AttachedCustomField'
    CustomFieldType:
      type: string
      description: Type of custom field
      x-extensible-enum:
      - PREDEFINED_FIELD_VALUES
      - FREE_TEXT
      example: PREDEFINED_FIELD_VALUES
    CustomField:
      type: object
      required:
      - fieldName
      - type
      anyOf:
      - required:
        - companyId
        - fieldName
        - type
      - required:
        - organizationId
        - fieldName
        - type
      properties:
        id:
          type: string
          example: '123456789'
        companyId:
          type: string
          example: '84000001'
          description: One of companyId or organizationId is required
        organizationId:
          type: string
          example: '84.1'
          description: One of companyId or organizationId is required
        fieldName:
          type: string
          example: color
          description: 'Acceptable characters are - alphanumeric, - (hyphen), _ (underscore), Empty character in the middle of character sequence

            '
          maxLength: 60
        type:
          $ref: '#/components/schemas/CustomFieldType'
        predefinedValues:
          description: 'List of predefined values.

            '
          type: array
          items:
            type: string
          example:
          - red
    IdType:
      type: string
      description: Type of identifier
      x-extensible-enum:
      - IMSI
      example: IMSI
    Problem:
      type: object
      example: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.4
      properties:
        type:
          type: string
          format: uri
          default: about:blank
          description: 'An absolute URI that identifies the problem type. When

            dereferenced,it SHOULD provide human-readable documentation

            for the problem type (e.g., using HTML).

            '
        title:
          type: string
          description: 'A short summary of the problem type in english and readable for

            engineers.

            '
          example: Bad Request
        status:
          type: integer
          format: int32
          description: 'The HTTP status code generated by the origin server for this

            occurrence of the problem.

            '
          minimum: 100
          example: 400
          exclusiveMaximum: 600
        detail:
          type: string
          description: 'A human readable explanation specific to this occurrence of the

            problem.

            '
          example: Uknown details
        instance:
          type: string
          description: 'An absolute URI that identifies the specific occurrence of the

            problem. It may or may not yield further information if

            dereferenced.

            '
    AttachedCustomField:
      type: object
      required:
      - fieldName
      - fieldValue
      properties:
        fieldName:
          type: string
          example: color
          description: 'Acceptable characters are - alphanumeric, - (hyphen), _ (underscore), Empty character in the middle of character sequence

            '
          maxLength: 60
        fieldValue:
          type: string
          example: red
          description: 'Acceptable characters are - alphanumeric, - (hyphen), _ (underscore), : (colon) ? (question mark) ( (open parenthesis) ) (close parenthesis) Empty character in the middle of character sequence

            '
          maxLength: 60
        fieldId:
          type: integer
          format: int64
          example: '123456'
    CustomFieldsResponse:
      type: object
      properties:
        items:
          description: 'Array of custom fields

            '
          type: array
          items:
            $ref: '#/components/schemas/CustomField'
    UpdateCustomFieldRequest:
      type: object
      properties:
        identifierType:
          $ref: '#/components/schemas/IdType'
        organizationId:
          type: string
          example: 1.23.45. If not specified, default company id of user is used.
        identifiers:
          description: 'List of identifiers to update.  Max number of items allowed is 100k.

            '
          type: array
          items:
            type: string
          example:
          - '123456789012345'
          - '123456789012346'
        customFields:
          $ref: '#/components/schemas/SubscriptionCustomFields'
  headers:
    X-RateLimit-Remaining-Minute:
      description: The number of requests remaining in a minute.
      schema:
        type: integer
        format: int32
    X-RateLimit-Limit-Second:
      description: The maximum number of requests allowed in a second.
      schema:
        type: integer
        format: int32
    X-RateLimit-Limit-Minute:
      description: The maximum number of requests allowed in a minute.
      schema:
        type: integer
        format: int32
    Content-Type:
      description: Handle Content-Type
      schema:
        type: string
    X-RateLimit-Remaining-Second:
      description: The number of requests remaining in a second.
      schema:
        type: integer
        format: int32
  responses:
    Response_403:
      description: Forbidden
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          examples:
            problem-response-example:
              value:
              - type: about:blank
                title: Forbidden
                status: 403
                detail: null
                instance: null
    Response_500:
      description: Internal Server Error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          examples:
            problem-response-example:
              value:
              - type: about:blank
                title: Internal Server Error
                status: 500
                detail: null
                instance: null
    Response_429:
      description: Too Many Requests
      allOf:
      - $ref: '#/components/responses/RateLimitedResponse'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          examples:
            problem-response-example:
              value:
              - type: about:blank
                title: Too Many Requests
                status: 429
                detail: Too Many Requests
                instance: null
    RateLimitedResponse:
      headers:
        X-RateLimit-Limit-Second:
          $ref: '#/components/headers/X-RateLimit-Limit-Second'
        X-RateLimit-Limit-Minute:
          $ref: '#/components/headers/X-RateLimit-Limit-Minute'
        X-RateLimit-Remaining-Second:
          $ref: '#/components/headers/X-RateLimit-Remaining-Second'
        X-RateLimit-Remaining-Minute:
          $ref: '#/components/headers/X-RateLimit-Remaining-Minute'
        Content-Type:
          $ref: '#/components/headers/Content-Type'
  securitySchemes:
    Oauth2_auth:
      flows:
        password:
          tokenUrl: https://iot-api.aeris.com/iot/api/auth/token
          scopes:
            custom-field.write: create or update custom fields
            custom-field.read: read custom fields
            subscription.write: update subscription
      type: oauth2