ncp_openapi.yaml

openapi: 3.0.0
info:
  title: Your API
  version: 1.0.0
servers:
  - url: https://yourapi.com
security:
  - BearerAuth: []
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
    Activity:
      type: object
      properties:
        transaction_date:
          type: integer
          format: int64
        title:
          type: string
        points_change:
          type: integer
    Household:
      type: object
      properties:
        name:
          type: string
        id:
          type: string
        points:
          type: integer
        last_transmission:
          type: integer
          format: int64
        membership_level:
          type: string
        weekly_points:
          type: integer
    Product:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        instructions:
          type: string
        introduction:
          type: string
        description:
          type: string
        disclaimer:
          type: string
        options:
          type: array
          items:
            type: object
            properties:
              dollars_value:
                type: integer
              points_value:
                type: integer
              product_option_id:
                type: string
    TokenNonce:
      type: object
      properties:
        token_nonce:
          type: string
    Purchase:
      type: object
      properties:
        product_id:
          type: string
        catalog_id:
          type: string
        quantity:
          type: integer
        token_nonce:
          type: string
        token_value:
          type: string
    Order:
      type: object
      properties:
        product_id:
          type: string
        catalog_id:
          type: string
        quantity:
          type: integer
    Message:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        body:
          type: string
        timestamp:
          type: integer
          format: int64
        read:
          type: boolean
    ReadStatus:
      type: object
      properties:
        read:
          type: boolean
paths:
  /auths:
    put:
      summary: Authenticate and get JWT
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                password:
                  type: string
                locale:
                  type: string
                external_id:
                  type: string
                csrf_challenge_token:
                  type: string
                captcha_response_token:
                  type: string
      responses:
        "200":
          description: JWT token
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /resets/{id}/passwords: # ID of the reset (contained in the link in the email)
    post:
      summary: Reset password
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                new_password:
                  type: string
                csrf_challenge_token:
                  type: string
                captcha_response_token:
                  type: string
      responses:
        "204":
          description: Password reset successful
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /config:
    get:
      summary: Get CMS key and market ID
      responses:
        "200":
          description: CMS key and market ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  cms_key:
                    type: string
                  catalogs:
                    type: array
                    items:
                      type: string
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /activity:
    get:
      summary: Get user activity data
      parameters:
        - name: start
          in: query
          required: false
          schema:
            type: integer
            format: int64
        - name: end
          in: query
          required: false
          schema:
            type: integer
            format: int64
      responses:
        "200":
          description: List of user activities
          content:
            application/json:
              schema:
                type: object
                properties:
                  activity:
                    type: array
                    items:
                      $ref: "#/components/schemas/Activity"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /household:
    get:
      summary: Get household data
      responses:
        "200":
          description: Household data
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Household"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /catalogs/{id}/products: # ID of the catalog of products
    get:
      summary: Get product data for a market
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Product data
          content:
            application/json:
              schema:
                type: object
                properties:
                  market_id:
                    type: string
                  products:
                    type: array
                    items:
                      $ref: "#/components/schemas/Product"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /tokens:
    post:
      summary: Generate 2FA token nonce
      responses:
        "200":
          description: Token nonce
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenNonce"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /purchases:
    put:
      summary: Create a purchase
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Purchase"
      responses:
        "204":
          description: Purchase successful
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /orders:
    get:
      summary: Check an order
      parameters:
        - name: product_id
          in: query
          required: true
          schema:
            type: string
        - name: catalog_id
          in: query
          required: true
          schema:
            type: string
        - name: quantity
          in: query
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: The order is valid
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /messages:
    get:
      summary: Get user messages
      responses:
        "200":
          description: List of messages
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      $ref: "#/components/schemas/Message"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /messages/{id}: # ID of the message
    patch:
      summary: Update message read status
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReadStatus"
      responses:
        "200":
          description: Updated message
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Message"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /users/{id}: # NCP user ID / Zendesk external ID
    get:
      summary: Retrieve user details
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the user
      responses:
        "200":
          description: User details retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  firstName:
                    type: string
                  lastName:
                    type: string
                  residenceAddress:
                    type: object
                    properties:
                      address:
                        type: string
                      city:
                        type: string
                      state:
                        type: string
                      zipCode:
                        type: string
                  mailingAddress:
                    type: object
                    properties:
                      useResidenceAddress:
                        type: boolean
                      address:
                        type: string
                      city:
                        type: string
                      state:
                        type: string
                      zipCode:
                        type: string
                  contactInformation:
                    type: object
                    properties:
                      homePhone:
                        type: string
                      workPhone:
                        type: string
                      mobile:
                        type: string
                      email:
                        type: string
                      emailVerified:
                        type: boolean
                      emailFormat:
                        type: string
                  operatingSystem:
                    type: string
                  requestNewStoreList:
                    type: boolean
                  optOutEmails:
                    type: boolean
                  optOutPhoneCalls:
                    type: boolean
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: User not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    patch:
      summary: Update user details
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                token_nonce:
                  type: string
                token_value:
                  type: string
                firstName:
                  type: string
                lastName:
                  type: string
                residenceAddress:
                  type: object
                  properties:
                    address:
                      type: string
                    city:
                      type: string
                    state:
                      type: string
                    zipCode:
                      type: string
                mailingAddress:
                  type: object
                  properties:
                    useResidenceAddress:
                      type: boolean
                    address:
                      type: string
                    city:
                      type: string
                    state:
                      type: string
                    zipCode:
                      type: string
                contactInformation:
                  type: object
                  properties:
                    homePhone:
                      type: string
                    workPhone:
                      type: string
                    mobile:
                      type: string
                    phoneNumberFor2FA:
                      type: string
                    email:
                      type: string
                    emailVerified:
                      type: string
                    emailFormat:
                      type: string
                operatingSystem:
                  type: string
                requestNewStoreList:
                  type: boolean
                optOutEmails:
                  type: boolean
                optOutPhoneCalls:
                  type: boolean
      responses:
        "200":
          description: User details updated successfully
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: User not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /login:
    get:
      summary: Login page
      responses:
        "200":
          description: HTML content for login
          content:
            text/html:
              schema:
                type: string
  /resets:
    post:
      summary: Password reset request
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                csrf_challenge_token:
                  type: string
                captcha_response_token:
                  type: string
      responses:
        "204":
          description: Reset successful
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    get:
      summary: Password reset confirmation page
      parameters:
        - name: token
          in: query
          required: true
          schema:
            type: string
          description: Token for the password reset process
      responses:
        "200":
          description: HTML content for password reset confirmation
          content:
            text/html:
              schema:
                type: string
        "404":
          description: Reset not found or expired
          content:
            text/html:
              schema:
                type: string
  /devices:
    post:
      summary: Create a new 2FA device
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - type
              properties:
                type:
                  type: string
                  enum:
                    - work
                    - home
                    - sms
                phoneNumber:
                  type: string
                  pattern: '^\+?[1-9]\d{1,14}$'
                label:
                  type: string
      responses:
        "201":
          description: 2FA device created and verification token sent
          content:
            application/json:
              schema:
                type: object
                properties:
                  deviceId:
                    type: string
                  message:
                    type: string
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /verifications:
    post:
      summary: Verify a 2FA device with a token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - deviceId
                - token
              properties:
                deviceId:
                  type: string
                token:
                  type: string
      responses:
        "200":
          description: 2FA device verified successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  deviceId:
                    type: string
                  verified:
                    type: boolean
        "400":
          description: Bad request or invalid token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Device not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"