swagger.yaml

swagger: "2.0"
info:
  version: "1.0.1"
  title: "Billing Account and Client API"
# during production,should point to your server machine
host: api.topcoder-dev.com
basePath: "/v3"
# during production, should use https
schemes:
- "https"
produces:
- application/json
consumes:
- application/json

securityDefinitions:
  Bearer:
    type: apiKey
    name: Authorization
    in: header

paths:
  /clients:
    get:
      tags:
        - client
      security:
        - Bearer: []
      operationId: findAllClients
      description: Retreive all clients. Availble to admin user only.
      parameters:
        - $ref: "#/parameters/offsetParam"
        - $ref: "#/parameters/limitParam"
        - name: filter
          required: true
          type: string
          in: query
          description: |
            Url encoded list of Supported filters
             - status
             - name
             - startDate
             - endDate
        - name: sort
          required: false
          description: |
            sort clients by status, name, startDate, endDate
          in: query
          type: string
      responses:
        '403':
          description: No permission or wrong token
          schema:
            $ref: "#/definitions/ErrorModel"
        '422':
          description: Invalid input
          schema:
            $ref: "#/definitions/ErrorModel"
        '200':
          description: A list of clients
          schema:
            $ref: "#/definitions/ClientListResponse"

    post:
      tags:
        - client
      security:
        - Bearer: []
      operationId: addNewClient
      description: Create a new client or update an existed client, Admin user only. If method is POST or not set, a new client will be created. You can update an exsiting client when method is PUT or PATCH
      parameters:
        - in: body
          name: body
          required: true
          schema:
            $ref: '#/definitions/NewClientBodyParam'
      responses:
        '403':
          description: No permission or wrong token
          schema:
            $ref: "#/definitions/ErrorModel"
        '201':
          description: Returns the newly created client
          schema:
            $ref: "#/definitions/ClientResponse"
        '422':
          description: Invalid input
          schema:
            $ref: "#/definitions/ErrorModel"


  /clients/{clientId}:
    get:
      tags:
        - client
      security:
        - Bearer: []
      description: Retrieve client by id, Admin user only.
      responses:
        '403':
          description: No permission or wrong token
          schema:
            $ref: "#/definitions/ErrorModel"
        '404':
          description: Not found
          schema:
            $ref: "#/definitions/ErrorModel"
        '200':
          description: a client
          schema:
            $ref: "#/definitions/ClientResponse"
      parameters:
        - $ref: "#/parameters/clientIdParam"
      operationId: getClientById

    patch:
      tags:
        - client
      security:
        - Bearer: []
      operationId: updateClient
      description: Update a client, Admin user only.
      responses:
        '403':
          description: No permission or wrong token
          schema:
            $ref: "#/definitions/ErrorModel"
        '404':
          description: Not found
          schema:
            $ref: "#/definitions/ErrorModel"
        '200':
          description: Successfully updated client. Returns updated client
          schema:
            $ref: "#/definitions/ClientResponse"
        '422':
          description: Invalid input
          schema:
            $ref: "#/definitions/ErrorModel"
        default:
          description: error payload
          schema:
            $ref: '#/definitions/ErrorModel'
      parameters:
        - $ref: "#/parameters/clientIdParam"
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/NewClientBodyParam"

  /billing-accounts:
    get:
      tags:
        - billingaccount
      security:
        - Bearer: []
      operationId: findBillingAccounts
      description: Retreive billing accounts that match the filter, Admin user only.
      responses:
        '403':
          description: No permission or wrong token
          schema:
            $ref: "#/definitions/ErrorModel"
        '400':
          description: Invalid input
          schema:
            $ref: "#/definitions/ErrorModel"
        '200':
          description: A list of billing accounts
          schema:
            $ref: "#/definitions/BillingAccountListResponse"
      parameters:
        - $ref: "#/parameters/offsetParam"
        - $ref: "#/parameters/limitParam"
        - name: filter
          required: true
          type: string
          in: query
          description: |
            Url encoded list of Supported filters
             - name
             - status
             - startDate
             - endDate
        - name: sort
          required: false
          description: |
            sort billing accounts by status, name, startDate, endDate
          in: query
          type: string

    post:
      tags:
        - billingaccount
      security:
        - Bearer: []
      operationId: addBillingAccount
      description: Create or update a billing account, Admin user only. If method is "POST", then it will create a new account. The account will be updated when method is "PUT" or "PATCH"
      parameters:
        - in: body
          name: body
          required: true
          schema:
            $ref: '#/definitions/NewBillingAccountBodyParam'
      responses:
        '403':
          description: No permission or wrong token
          schema:
            $ref: "#/definitions/ErrorModel"
        '201':
          description: Returns the newly created billing account
          schema:
            $ref: "#/definitions/BillingAccountResponse"
        '400':
          description: Invalid input
          schema:
            $ref: "#/definitions/ErrorModel"

  /billing-accounts/{billingAccountId}:
    get:
      tags:
        - billingaccount
      security:
        - Bearer: []
      description: Retrieve billing account by id, Admin user only.
      responses:
        '403':
          description: No permission or wrong token
          schema:
            $ref: "#/definitions/ErrorModel"
        '404':
          description: Not found
          schema:
            $ref: "#/definitions/ErrorModel"
        '200':
          description: a billing account
          schema:
            $ref: "#/definitions/BillingAccountResponse"
      parameters:
        - $ref: "#/parameters/billingAcountIdParam"
      operationId: getBillingAccount

    patch:
      tags:
        - billingaccount
      security:
        - Bearer: []
      operationId: updateBillingAccount
      description: Update a billing account, Admin user only.
      responses:
        '403':
          description: No permission or wrong token
          schema:
            $ref: "#/definitions/ErrorModel"
        '404':
          description: Not found
          schema:
            $ref: "#/definitions/ErrorModel"
        '200':
          description: Successfully updated billing account. Returns original and updated billing account object
          schema:
            $ref: "#/definitions/UpdateBillingAccountResponse"
        '400':
          description: Invalid input
          schema:
            $ref: "#/definitions/ErrorModel"
        default:
          description: error payload
          schema:
            $ref: '#/definitions/ErrorModel'
      parameters:
        - $ref: "#/parameters/billingAcountIdParam"
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/BillingAccountBodyParam"

  /billing-accounts/{billingAccountId}/users:
    get:
      tags:
        - billingaccount
      security:
        - Bearer: []
      description: Retrieve users of billing account, Admin user only.
      operationId: getBillingAccountUsers
      responses:
        '403':
          description: No permission or wrong token
          schema:
            $ref: "#/definitions/ErrorModel"
        '404':
          description: Not found
          schema:
            $ref: "#/definitions/ErrorModel"
        '200':
          description: users of billing account
          schema:
            $ref: "#/definitions/BillingAccountUserListResponse"
      parameters:
        - $ref: "#/parameters/billingAcountIdParam"
        - $ref: "#/parameters/offsetParam"
        - $ref: "#/parameters/limitParam"

    post:
      tags:
        - billingaccount
      security:
        - Bearer: []
      description: Assign user to billing account, Admin user only.
      operationId: assignUserToBillingAccount
      responses:
        '403':
          description: No permission or wrong token
          schema:
            $ref: "#/definitions/ErrorModel"
        '404':
          description: Not found
          schema:
            $ref: "#/definitions/ErrorModel"
        '200':
          description: a billing account
          schema:
            $ref: "#/definitions/BillingAccountResponse"
      parameters:
        - $ref: "#/parameters/billingAcountIdParam"
        - in: body
          name: body
          required: true
          schema:
            $ref: "#/definitions/AddAccountUserRequest"

  /billing-accounts/{billingAccountId}/users/{userId}:
    delete:
      tags:
        - billingaccount
      security:
        - Bearer: []
      description: Remove user from billing account, Admin user only.
      operationId: removeUserFromBillingAccount
      responses:
        '403':
          description: No permission or wrong token
          schema:
            $ref: "#/definitions/ErrorModel"
        '404':
          description: Not found
          schema:
            $ref: "#/definitions/ErrorModel"
        '204':
          description: successful operation
      parameters:
        - $ref: "#/parameters/billingAcountIdParam"
        - $ref: "#/parameters/userIdParam"

  /me/billing-accounts:
    get:
      tags:
        - billingaccount
      security:
        - Bearer: []
      operationId: findBillingAccountsByUser
      description: Retreive billing accounts that match the filter, For admin and non-admin user.
      responses:
        '403':
          description: No permission or wrong token
          schema:
            $ref: "#/definitions/ErrorModel"
        '400':
          description: Invalid input
          schema:
            $ref: "#/definitions/ErrorModel"
        '200':
          description: A list of billing accounts
          schema:
            $ref: "#/definitions/BillingAccountListResponse"
      parameters:
        - $ref: "#/parameters/offsetParam"
        - $ref: "#/parameters/limitParam"
        - name: filter
          required: true
          type: string
          in: query
          description: |
            Url encoded list of Supported filters
             - name
             - status
             - startDate
             - endDate
        - name: sort
          required: false
          description: |
            sort billing accounts by name, status, startDate, endDate
          in: query
          type: string
  /billing-accounts/{billingAccountId}/fees:
    get:
      tags:
        - challengeFees
      security:
        - Bearer: []
      operationId: getBillingAccountFees
      description: Retrieve challenge fees by billing account id, Admin user only.
      responses:
        '200':
          description: Return challenge fees
          schema:
            $ref: "#/definitions/ChallengeFeesResponse"
        '401':
          description: Miss authentication credentials
          schema:
            $ref: "#/definitions/ErrorModel"
        '403':
          description: No permission or wrong token
          schema:
            $ref: "#/definitions/ErrorModel"
        '404':
          description: Not found
          schema:
            $ref: "#/definitions/ErrorModel"
        '500':
          description: Internal server error
          schema:
            $ref: "#/definitions/ErrorModel"
      parameters:
        - $ref: "#/parameters/billingAcountIdParam"
      
    post:
      tags:
        - challengeFees
      security:
        - Bearer: []
      operationId: createBillingAccountFees
      description: Create billing account fees, Admin user only. Please check the document of BillingAccountChallengeFees entity definition about how to prepare the ChallengeFeesBodyParam
      responses:
        '200':
          description: Return the created challenge fees
          schema:
            $ref: "#/definitions/ChallengeFeesResponse"
        '400':
          description: Bad request data
          schema:
            $ref: "#/definitions/ErrorModel"
        '401':
          description: Miss authentication credentials
          schema:
            $ref: "#/definitions/ErrorModel"
        '403':
          description: No permission or wrong token
          schema:
            $ref: "#/definitions/ErrorModel"
        '404':
          description: Not found
          schema:
            $ref: "#/definitions/ErrorModel"
        '500':
          description: Internal server error
          schema:
            $ref: "#/definitions/ErrorModel"
      parameters:
        - $ref: "#/parameters/billingAcountIdParam"
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/ChallengeFeesBodyParam"

    put:
      tags:
        - challengeFees
      security:
        - Bearer: []
      operationId: updateBillingAccountFees
      description: Update billing account fees, Admin user only. Please check the document of BillingAccountChallengeFees entity definition about how to prepare the ChallengeFeesBodyParam
      responses:
        '200':
          description: Return the updated challenge fees
          schema:
            $ref: "#/definitions/ChallengeFeesResponse"
        '400':
          description: Bad request data
          schema:
            $ref: "#/definitions/ErrorModel"
        '401':
          description: Miss authentication credentials
          schema:
            $ref: "#/definitions/ErrorModel"
        '403':
          description: No permission or wrong token
          schema:
            $ref: "#/definitions/ErrorModel"
        '404':
          description: Not found
          schema:
            $ref: "#/definitions/ErrorModel"
        '500':
          description: Internal server error
          schema:
            $ref: "#/definitions/ErrorModel"
      parameters:
        - $ref: "#/parameters/billingAcountIdParam"
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/ChallengeFeesBodyParam"

parameters:
  clientIdParam:
    name: clientId
    in: path
    description: client identifier
    required: true
    type: integer
    format: int64
  billingAcountIdParam:
    name: billingAccountId
    in: path
    description: billing account identifier
    required: true
    type: integer
    format: int64
  userIdParam:
    name: userId
    in: path
    description: user identifier
    required: true
    type: integer
    format: int64
  offsetParam:
    name: offset
    description: "number of items to skip. Defaults to 0"
    in: query
    required: false
    type: integer
    format: int32
  limitParam:
    name: limit
    description: "max records to return. Defaults to 10"
    in: query
    required: false
    type: integer
    format: int32

definitions:
  ResponseMetadata:
    title: Metadata object for a response
    type: object
    properties:
      totalCount:
        type: integer
        format: int64
        description: Total count of the objects

  ErrorModel:
    type: object
    properties:
      id:
        type: string
        description: unique id identifying the request
      version:
        type: string
      result:
        type: object
        properties:
          success:
            type: boolean
          status:
            description: http status code
            type: integer
            format: int32
          debug:
            type: object
          content:
            type: object

  NewClient:
    type: object
    required:
       - name
       - status
    properties:
      name:
        type: string
        description: The client name (up to 64 characters)
      status:
        type: string
        description: the client status (ACTIVE or INACTIVE)
      startDate:
        type: string
        description: billing account start date, Datetime (GMT)
      endDate:
        type: string
        description: billing account end date, Datetime (GMT)
      codeName:
        type: string
        description: the client code name (optional)
      customerNumber:
        type: string
        description: the client customer number. This is an external reference code (optional)

  NewBillingAccount:
    type: object
    required:
       - name
       - companyId
       - clientId
    properties:
      name:
        type: string
        description: billing account name (up to 64 characters)      
      description:
        type: string
        description: billing account description (up to 255 characters)
      status:
        type: string
        description: BillingAccount status (ACTIVE or INACTIVE)
      startDate:
        type: string
        description: billing account start date, Datetime (GMT)
      endDate:
        type: string
        description: billing account end date, Datetime (GMT)
      companyId:
        type: number
        description: The company id. This will always be set to 1.
      subscriptionNumber:
        type: number
        description: The subscription number. Reference to a customer subscription.
      manualPrizeSetting:
        type: number
        description: The manual prize setting. Not used.  Set to 0.
      clientId:
        type: number
        description: The client id. Set this to the client that the billing account is for.
      poNumber:
        type: string
        description: The PO number as defined by finance.
      paymentTerms:
        $ref: "#/definitions/PaymentTerms"
      salesTax:
        type: number
        description: The billing account sales tax.
      budgetAmount:
        type: number
        description: The billing account budget amount.
      billable:
        type: boolean
        description: The flag indicating whether this account is billable. If unset it will be set to false.
          
  PaymentTerms:
   type: object
   properties:
    id:
     type: number
     description: The payment terms id.
    description:
     type: string
     description : The payment terms description.
  
  NewBillingAccountBodyParam:
    type: object
    properties:
      param:
        $ref: "#/definitions/NewBillingAccount"
      method:
        type: string
        description: should be POST, PUT, or PATCH

  NewClientBodyParam:
    type: object
    properties:
      param:
        $ref: "#/definitions/NewClient"
      method:
        type: string
        description: Should be POST, PUT, or PATCH

  BillingAccountBodyParam:
    type: object
    properties:
      param:
        $ref: "#/definitions/BillingAccount"

  Client:
    type: object
    properties:
      id:
        description: unique identifier
        type: integer
        format: int64
      name:
        type: string
        description: The client name
      status:
        type: string
        description: The client status
      startDate:
        type: string
        description: billing account start date, Datetime (GMT)
      endDate:
        type: string
        description: billing account end date, Datetime (GMT)
      codeName:
        type: string
        description: The client code name
      customerNumber:
        type: string
        description: The client customer number

  ClientResponse:
    title: Single client
    type: object
    properties:
      id:
        type: string
        description: unique id identifying the request
      version:
        type: string
      result:
        type: object
        properties:
          success:
            type: boolean
          status:
            type: string
          content:
            $ref: "#/definitions/Client"

  ClientListResponse:
    title: List response
    type: object
    properties:
      id:
        type: string
        readOnly: true
        description: unique id identifying the request
      version:
        type: string
      result:
        type: object
        properties:
          success:
            type: boolean
          status:
            type: string
          metadata:
            $ref: "#/definitions/ResponseMetadata"
          content:
            type: array
            items:
              $ref: "#/definitions/Client"

  BillingAccount:
    type: object
    properties:
      id:
        description: unique identifier
        type: integer
        format: int64      
      name:
        type: string
        description: billing account name
      status:
        type: string
        description: billing account status
      startDate:
        type: string
        description: billing account start date, Datetime (GMT)
      endDate:
        type: string
        description: billing account end date, Datetime (GMT)
      budgetAmount:
        type: number
        format: float
        description: the challenge budget for this billing account.
      description:
        type: string
        description: the description for this billing account.
      poNumber:
        type: number
        format: int64
        description: the po number for this billing account.
      paymentTerms:
        type: string
        description: the payment terms for this billing account.
      subscriptionNumber:
        type: number
        format: float
        description: the subscription number for this billing account.
      companyId:
        type: number
        description: The company id
      manualPrizeSetting:
        type: number
        description: The manual prize setting
      clientId:
        type: number
        description: The client id  
      billable:
        type: boolean
        description: the flag indicating the account is billable.
      createdAt:
        type: string
        description: Datetime (GMT) when task was created
        readOnly: true
      createdBy:
        type: integer
        format: int64
        description: READ-ONLY. User who created this task
        readOnly: true
      updatedAt:
        type: string
        description: READ-ONLY. Datetime (GMT) when task was updated
        readOnly: true
      updatedBy:
        type: integer
        format: int64
        description: READ-ONLY. User that last updated this task
        readOnly: true
      

  BillingAccountUser:
    type: object
    properties:
      id:
        description: unique identifier
        type: integer
        format: int64
      name:
        type: string
        description: billing account name
      description:
        type: string
        description: BillingAccount description

  BillingAccountResponse:
    title: Single billing account object
    type: object
    properties:
      id:
        type: string
        description: unique id identifying the request
      version:
        type: string
      result:
        type: object
        properties:
          success:
            type: boolean
          status:
            type: string
          content:
            $ref: "#/definitions/BillingAccount"

  UpdateBillingAccountResponse:
    title: response with original and updated billing account object
    type: object
    properties:
      id:
        type: string
        description: unique id identifying the request
      version:
        type: string
      result:
        type: object
        properties:
          success:
            type: boolean
          status:
            type: string
            description: http status code
          content:
            type: object
            properties:
              original:
                $ref: "#/definitions/BillingAccount"
              updated:
                 $ref: "#/definitions/BillingAccount"

  BillingAccountListResponse:
    title: List response
    type: object
    properties:
      id:
        type: string
        readOnly: true
        description: unique id identifying the request
      version:
        type: string
      result:
        type: object
        properties:
          success:
            type: boolean
          status:
            type: string
          metadata:
            $ref: "#/definitions/ResponseMetadata"
          content:
            type: array
            items:
              $ref: "#/definitions/BillingAccount"
  AddAccountUserRequest:
    title: The request to add a user to an account.
    type: object
    properties:
      userId:
        type: integer

  BillingAccountUserListResponse:
    title: List response
    type: object
    properties:
      id:
        type: string
        readOnly: true
        description: unique id identifying the request
      version:
        type: string
      result:
        type: object
        properties:
          success:
            type: boolean
          status:
            type: string
          metadata:
            $ref: "#/definitions/ResponseMetadata"
          content:
            type: array
            items:
              $ref: "#/definitions/BillingAccountUser"

  ChallengeFeesBodyParam:
    type: object
    properties:
      param:
        type: array
        items:
          $ref: "#/definitions/BillingAccountChallengeFees"
      method:
        type: string
        description: should be POST, PUT

  ChallengeFeesResponse:
    title: List response
    type: object
    properties:
      id:
        type: string
        readOnly: true
        description: unique id identifying the request
      version:
        type: string
      result:
        type: object
        properties:
          success:
            type: boolean
          status:
            type: string
          metadata:
            $ref: "#/definitions/ResponseMetadata"
          content:
            type: array
            items:
              $ref: "#/definitions/BillingAccountChallengeFees"
  BillingAccountChallengeFees:
    type: object
    properties:
      challengeFeeFixed:
        description: >-
          If it's true, the challengeFeePercentage field should not be present, but the challengeFees field should be present. 
          If it's false, the challengeFeePercentage field should be present and the challengeFees field should not be present.
        type: boolean
      challengeFeePercentage:
        description: >-
          This field should be present only if the challengeFeeFixed field is false.
        type: number
        format: double
      challengeFees:
        description: This field should be present only if the challengeFeeFixed is set to true
        type: array
        items:
          type: object
          properties:
            id:
              description: unique identifier
              type: integer
              format: int64
            name:
              type: string
              description: billing account name
            projectId:
              type: number
              format: int64
            studio:
              type: boolean
            challengeTypeId:
              type: number
              format: int64
            challengeTypeDescription:
              type: string
            challengeFee:
              type: number
              format: double
            createdAt:
              type: string
              description: Datetime (GMT) when task was created
              readOnly: true
            createdBy:
              type: integer
              format: int64
              description: READ-ONLY. User who created this task
              readOnly: true
            updatedAt:
              type: string
              description: READ-ONLY. Datetime (GMT) when task was updated
              readOnly: true
            updatedBy:
              type: integer
              format: int64
              description: READ-ONLY. User that last updated this task
              readOnly: true