openapi: 3.0.2
info:
  title: MobileHelp - Phoenix API
  description: MobileHelp RESTFul API for the Phoenix application.
  version: 1.0.0
  contact:
    name: MobileHelp API Support
    email: api-support@mobilehelp.com
servers:
  - url: https://api.phoenix.dev.mobilehelp.io
    description: Development
  - url: https://api.phoenix.mobilehelp.com
    description: Production
security:
  - BearerAuth: []
paths:
  /account-reactivations/:
    post:
      summary: Create a job
      description: Create a job to be processed asynchronously.
      operationId: createJob
      tags:
        - account-reactivation
      requestBody:
        description: Create a job.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/JobRequest"
      responses:
        "200":
          description: The job request was created and it will be processed
            asynchronously. Returns job summary.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobSummary"
          headers:
            location:
              $ref: "#/components/headers/location"
        "400":
          $ref: "#/components/responses/validationError"
      x-maturity:
        - beta
      x-amazon-apigateway-integration:
        type: aws_proxy
        httpMethod: POST
        uri:
          Fn::Join:
            - ""
            - - "arn:aws:apigateway:"
              - Ref: AWS::Region
              - :lambda:path/2015-03-31/functions/
              - Fn::GetAtt:
                  - CreateJobLambdaFunction
                  - Arn
              - /invocations
    get:
      summary: List jobs
      description: List jobs summary in the queue based on filtering criteria.
      operationId: listJobs
      tags:
        - account-reactivation
      parameters:
        - $ref: "#/components/parameters/page"
        - $ref: "#/components/parameters/dateRange"
        - name: dealerId
          in: query
          schema:
            type: integer
        - name: status
          in: query
          schema:
            $ref: "#/components/schemas/JobStatus"
      responses:
        "200":
          description: Jobs in the queue matching the filtering criteria.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobList"
      x-maturity:
        - beta
      x-amazon-apigateway-integration:
        type: aws_proxy
        httpMethod: POST
        uri:
          Fn::Join:
            - ""
            - - "arn:aws:apigateway:"
              - Ref: AWS::Region
              - :lambda:path/2015-03-31/functions/
              - Fn::GetAtt:
                  - ListJobsLambdaFunction
                  - Arn
              - /invocations
  "/account-reactivations/{id}":
    get:
      summary: Get job summary by ID
      operationId: getJob
      tags:
        - account-reactivation
      parameters:
        - $ref: "#/components/parameters/jobId"
      responses:
        "200":
          description: Job summary.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobSummary"
        "404":
          description: Job ID not found.
      x-maturity:
        - beta
      x-amazon-apigateway-integration:
        type: aws_proxy
        httpMethod: POST
        uri:
          Fn::Join:
            - ""
            - - "arn:aws:apigateway:"
              - Ref: AWS::Region
              - :lambda:path/2015-03-31/functions/
              - Fn::GetAtt:
                  - GetJobLambdaFunction
                  - Arn
              - /invocations
  "/account-reactivations/{id}/accounts":
    get:
      summary: List job accounts
      description: List job accounts based on filtering criteria.
      operationId: listJobAccounts
      tags:
        - account-reactivation
      parameters:
        - $ref: "#/components/parameters/jobId"
        - $ref: "#/components/parameters/page"
        - name: status
          in: query
          schema:
            $ref: "#/components/schemas/AccountStageStatus"
      responses:
        "200":
          description: Job accounts.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobAccounts"
        "404":
          description: Job ID not found.
      x-maturity:
        - beta
      x-amazon-apigateway-integration:
        type: aws_proxy
        httpMethod: POST
        uri:
          Fn::Join:
            - ""
            - - "arn:aws:apigateway:"
              - Ref: AWS::Region
              - :lambda:path/2015-03-31/functions/
              - Fn::GetAtt:
                  - ListJobAccountsLambdaFunction
                  - Arn
              - /invocations
  "/account-reactivations/{id}/audit-log":
    get:
      summary: List job audit log entries
      operationId: listJobAuditLog
      tags:
        - account-reactivation
      parameters:
        - $ref: "#/components/parameters/jobId"
        - $ref: "#/components/parameters/page"
      responses:
        "200":
          description: Job audit entries.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuditLogList"
        "404":
          description: Job ID not found.
      x-maturity:
        - beta
      x-amazon-apigateway-integration:
        type: aws_proxy
        httpMethod: POST
        uri:
          Fn::Join:
            - ""
            - - "arn:aws:apigateway:"
              - Ref: AWS::Region
              - :lambda:path/2015-03-31/functions/
              - Fn::GetAtt:
                  - ListJobAuditLogLambdaFunction
                  - Arn
              - /invocations
  "/account-reactivations/{id}/retry":
    post:
      summary: Retry job.
      description: Retries failed accounts in the job.
      operationId: retryJob
      tags:
        - account-reactivation
      parameters:
        - $ref: "#/components/parameters/jobId"
      responses:
        "204":
          description: Failed job accounts will be retried.
        "404":
          description: Job ID not found.
      x-maturity:
        - beta
      x-amazon-apigateway-integration:
        type: aws_proxy
        httpMethod: POST
        uri:
          Fn::Join:
            - ""
            - - "arn:aws:apigateway:"
              - Ref: AWS::Region
              - :lambda:path/2015-03-31/functions/
              - Fn::GetAtt:
                  - RetryJobLambdaFunction
                  - Arn
              - /invocations
  "/account-reactivations/{id}/cancel":
    post:
      summary: Cancel job.
      description: Cancel pending accounts in the job.
      operationId: cancelJob
      tags:
        - account-reactivation
      parameters:
        - $ref: "#/components/parameters/jobId"
      responses:
        "204":
          description: Job is been cancelled.
        "404":
          description: Job ID not found.
      x-maturity:
        - beta
      x-amazon-apigateway-integration:
        type: aws_proxy
        httpMethod: POST
        uri:
          Fn::Join:
            - ""
            - - "arn:aws:apigateway:"
              - Ref: AWS::Region
              - :lambda:path/2015-03-31/functions/
              - Fn::GetAtt:
                  - CancelJobLambdaFunction
                  - Arn
              - /invocations
  "/account-reactivations/{id}/download":
    get:
      summary: Download account status
      description: Download job account status and details in CSV format.
      operationId: downloadJob
      tags:
        - account-reactivation
      parameters:
        - $ref: "#/components/parameters/jobId"
      responses:
        "200":
          description: Job accounts details are ready to be downloaded.
          content:
            text/csv:
              schema:
                type: string
        "404":
          description: Job ID not found.
      x-maturity:
        - beta
      x-amazon-apigateway-integration:
        type: aws_proxy
        httpMethod: POST
        uri:
          Fn::Join:
            - ""
            - - "arn:aws:apigateway:"
              - Ref: AWS::Region
              - :lambda:path/2015-03-31/functions/
              - Fn::GetAtt:
                  - DownloadJobLambdaFunction
                  - Arn
              - /invocations
  /dealers/:
    get:
      summary: Get dealers
      description: Get a list of dealers from given search criteria
      parameters:
        - in: query
          name: name
          required: false
          schema:
            type: string
            pattern: ^[a-zA-Z0-9 ]*$
          description: Partial or complete name of a dealer
          example: business
      operationId: getDealers
      tags:
        - dealer
      responses:
        "200":
          description: Dealers matching the filtering criteria.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Dealer"
      x-maturity:
        - beta
      x-amazon-apigateway-integration:
        type: aws_proxy
        httpMethod: POST
        uri:
          Fn::Join:
            - ""
            - - "arn:aws:apigateway:"
              - Ref: AWS::Region
              - :lambda:path/2015-03-31/functions/
              - Fn::GetAtt:
                  - GetDealersLambdaFunction
                  - Arn
              - /invocations
  "/dealers/{id}":
    get:
      summary: Get dealer by ID
      description: Retrieve a single dealer from given dealer ID
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: number
          description: Dealer ID
          example: 123456
      operationId: getDealer
      tags:
        - dealer
      responses:
        "200":
          description: Dealer with the given ID
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Dealer"
        "404":
          description: Dealer not found
      x-maturity:
        - beta
      x-amazon-apigateway-integration:
        type: aws_proxy
        httpMethod: POST
        uri:
          Fn::Join:
            - ""
            - - "arn:aws:apigateway:"
              - Ref: AWS::Region
              - :lambda:path/2015-03-31/functions/
              - Fn::GetAtt:
                  - GetDealerLambdaFunction
                  - Arn
              - /invocations
components:
  securitySchemes:
    BearerAuth:
      type: apiKey
      name: Authorization
      in: header
  schemas:
    Account:
      type: object
      required:
        - id
        - devices
        - status
        - alxStatus
        - it3Status
      properties:
        id:
          $ref: "#/components/schemas/AccountID"
        devices:
          type: array
          minItems: 0
          maxItems: 2
          items:
            $ref: "#/components/schemas/Device"
        status:
          $ref: "#/components/schemas/StageStatus"
        alxStatus:
          $ref: "#/components/schemas/StageStatus"
        it3Status:
          $ref: "#/components/schemas/StageStatus"
    AccountID:
      type: string
      pattern: ^[a-zA-Z\d]+$
      example: MMHB625487
    AccountList:
      type: object
      required:
        - totalCount
        - data
      properties:
        totalCount:
          type: integer
        data:
          type: array
          items:
            $ref: "#/components/schemas/Account"
    AccountStageStatus:
      type: string
      enum:
        - pending
        - successful
        - unsuccessful
    AuditLog:
      type: object
      required:
        - date
        - user
        - action
      properties:
        date:
          type: string
          format: date-time
        patch:
          type: string
        user:
          $ref: "#/components/schemas/User"
        action:
          type: string
          enum:
            - create
            - retry
            - download
            - start
            - complete
    AuditLogList:
      type: object
      required:
        - totalCount
        - data
      properties:
        totalCount:
          type: integer
          minimum: 0
        data:
          type: array
          items:
            $ref: "#/components/schemas/AuditLog"
    Created:
      type: object
      required:
        - user
        - date
      properties:
        user:
          $ref: "#/components/schemas/User"
        date:
          type: string
          format: date-time
    Dealer:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          example: 18354
        name:
          type: string
          example: ADT
    Device:
      type: object
      required:
        - serial
        - sim
        - status
      properties:
        serial:
          type: string
          example: M78XWQ29XM
        sim:
          type: string
          example: "89012345678901234567"
        status:
          $ref: "#/components/schemas/StageStatus"
    JobAccounts:
      type: object
      required:
        - summary
        - accounts
      properties:
        summary:
          $ref: "#/components/schemas/JobSummary"
        accounts:
          $ref: "#/components/schemas/AccountList"
    JobList:
      type: object
      required:
        - totalCount
        - data
      properties:
        totalCount:
          type: integer
          minimum: 0
        data:
          type: array
          items:
            $ref: "#/components/schemas/JobSummary"
    JobRequest:
      type: object
      required:
        - type
        - dealerId
        - accountType
        - accounts
      properties:
        type:
          $ref: "#/components/schemas/JobType"
        dealerId:
          type: number
          example: 18547
        accountType:
          $ref: "#/components/schemas/AccountType"
        accounts:
          type: array
          description: Accounts in the job. Must be unique items.
          minItems: 1
          maxItems: 2000
          items:
            $ref: "#/components/schemas/AccountID"
        notify:
          description: Emails that will receive notifications. Must be unique items.
          type: array
          minItems: 0
          maxItems: 10
          items:
            type: string
            format: email
            pattern: ^.+@(cleararchhealth|mobilehelp)\.com$
            example:
              - some.user@mobilehelp.com
              - john.smith@cleararchhealth.com
    JobSummary:
      type: object
      required:
        - id
        - type
        - created
        - dealer
        - status
        - notify
        - accountType
      properties:
        id:
          type: string
        type:
          $ref: "#/components/schemas/JobType"
        created:
          $ref: "#/components/schemas/Created"
        dealer:
          $ref: "#/components/schemas/Dealer"
        accountType:
          $ref: "#/components/schemas/AccountType"
        status:
          type: object
          required:
            - current
            - percentage
            - pending
            - successful
            - unsuccessful
          properties:
            current:
              $ref: "#/components/schemas/JobStatus"
            percentage:
              type: number
              example: 33
            pending:
              type: number
              example: 40
            successful:
              type: number
              example: 17
            unsuccessful:
              type: number
              example: 3
        notify:
          type: array
          items:
            type: string
            format: email
            example:
              - some.user@mobilehelp.com
              - john.smith@cleararchhealth.com
    StageStatus:
      type: object
      required:
        - status
        - errors
      properties:
        status:
          type: string
          enum:
            - pending
            - skipped
            - successful
            - unsuccessful
        errors:
          type: array
          minItems: 0
          items:
            type: string
    User:
      type: object
      required:
        - id
        - username
        - email
        - firstName
        - lastName
        - providerName
      properties:
        id:
          type: string
          example: john.smith@mobilehelp.com
        username:
          type: string
          example: it3-azure-ad_John.Smith@mobilehelp.com
        email:
          type: string
          format: email
          example: john.smith@mobilehelp.com
        firstName:
          type: string
          example: John
        lastName:
          type: string
          example: Smith
        providerName:
          type: string
          example: it3-azure-ad
    AccountType:
      type: string
      enum:
        - csid
        - m3id
    JobStatus:
      type: string
      enum:
        - completed
        - inProgress
        - cancelled
    JobType:
      type: string
      enum:
        - reactivate
        - deactivate
    RequestValidationError:
      type: object
      required:
        - message
      properties:
        location:
          type: string
          enum:
            - body
            - headers
            - path
            - query
          example: body
        path:
          type: string
          example: patient.address.zipCode
        message:
          type: string
          example: must match pattern "^\d{5}$"
    RequestValidationErrors:
      type: array
      minItems: 1
      items:
        $ref: "#/components/schemas/RequestValidationError"
    JobRequestAccepted:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          example: X645A78B0
    Page:
      type: object
      required:
        - index
        - size
      properties:
        index:
          description: Page to show. Index is base 1.
          type: integer
          minimum: 1
        size:
          type: integer
          minimum: 10
          maximum: 25
    DateRange:
      type: object
      properties:
        from:
          type: string
          format: date-time
        to:
          type: string
          format: date-time
  responses:
    validationError:
      description: The request contained invalid data and it has been rejected.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/RequestValidationErrors"
    corsPreflightResponse:
      description: CORS preflight response
      headers:
        Access-Control-Allow-Origin:
          schema:
            type: string
        Access-Control-Allow-Methods:
          schema:
            type: string
        Access-Control-Allow-Headers:
          schema:
            type: string
      content: {}
  parameters:
    jobId:
      name: id
      in: path
      required: true
      schema:
        type: string
    page:
      name: page
      in: query
      required: true
      schema:
        $ref: "#/components/schemas/Page"
    dateRange:
      name: dateRange
      in: query
      schema:
        $ref: "#/components/schemas/DateRange"
  headers:
    location:
      description: URI of the new resource.
      schema:
        type: string
x-maturity:
  - name: ga
    description: This API is generally available.
  - name: beta
    description: Please note that this is a beta product and is subject to change.
      Use it with caution.
x-amazon-apigateway-request-validators:
  all:
    validateRequestBody: true
    validateRequestParameters: true
x-amazon-apigateway-gateway-responses:
  DEFAULT_4XX:
    responseParameters:
      gatewayresponse.header.Access-Control-Allow-Methods: "'${param:ACCESS_CONTROL_ALLOW_METHODS}'"
      gatewayresponse.header.Access-Control-Allow-Headers: "'${param:ACCESS_CONTROL_ALLOW_HEADERS}'"
      gatewayresponse.header.Access-Control-Allow-Origin: "'${param:ACCESS_CONTROL_ALLOW_ORIGIN}'"
  DEFAULT_5XX:
    responseParameters:
      gatewayresponse.header.Access-Control-Allow-Methods: "'${param:ACCESS_CONTROL_ALLOW_METHODS}'"
      gatewayresponse.header.Access-Control-Allow-Headers: "'${param:ACCESS_CONTROL_ALLOW_HEADERS}'"
      gatewayresponse.header.Access-Control-Allow-Origin: "'${param:ACCESS_CONTROL_ALLOW_ORIGIN}'"