openapi: 3.1.0
info:
  title: Avibra Integration API
  description: ''
  version: 1.0.2
tags: []
paths:
  /user/account/create:
    post:
      summary: Create User
      deprecated: false
      description: >-
        The API is used to create a user account within the Avibra ecosystem.
        Ensure a unique Idempotency-Key header is included to prevent duplicate
        account creation. Use the header Version: v2 to enable idempotency and
        synchronous API execution.
      tags: []
      parameters:
        - name: Content-Type
          in: header
          description: ''
          required: true
          example: application/json
          schema:
            type: string
        - name: Idempotency-Key
          in: header
          description: Unique Key to identify same request.
          required: true
          example: '{{$string.uuid}}'
          schema:
            type: string
        - name: Version
          in: header
          description: ''
          required: true
          example: '{{version}}'
          schema:
            type: string
        - name: x-api-key
          in: header
          description: ''
          required: false
          example: ''
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/userInfo'
            example:
              firstname: James
              lastname: Smith
              email: example@email.com
              zipcode: '10001'
              dob: '2000-03-03'
              partneroffer: '{{offername}}'
              userid: '{{userid}}'
              phone: '1234123412'
              gender: M
              address:
                addline1: 123 Bond Street
                addline2: ''
                addline3: ''
                city: NY
                state: NY
                zipcode: '10001'
              benefits:
                - life
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: string
              example: Successful
          headers: {}
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorInfo'
              example:
                id: '400'
                message: Invalid email
          headers: {}
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorInfo'
              example:
                id: '401'
                message: Unauthorized
          headers: {}
        '409':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorInfo'
              example:
                id: '409'
                message: User already onboarded
          headers: {}
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorInfo'
              example:
                id: '500'
                message: >-
                  Internal Server Error.
                  ErrorReference:cdb6f1c3-2d2b-44b9-9ef1-4b34de567357
          headers: {}
      security:
        - bearer: []
  /user/account/update:
    post:
      summary: Update User
      deprecated: false
      description: >-
        This API is used to update a user's first name, last name, email, or
        phone number. Include a unique Idempotency-Key header to prevent
        duplicate updates. Use the header Version: v2 to enable idempotency and
        ensure synchronous API execution.
      tags: []
      parameters:
        - name: Content-Type
          in: header
          description: ''
          required: true
          example: application/json
          schema:
            type: string
        - name: Idempotency-Key
          in: header
          description: ''
          required: true
          example: ''
          schema:
            type: string
        - name: Version
          in: header
          description: ''
          required: true
          example: ''
          schema:
            type: string
        - name: x-api-key
          in: header
          description: ''
          required: false
          example: ''
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/updateuserInfo'
            example:
              userid: ''
              partnername: ''
              firstname: jane
              lastname: doe
              email: example@email.com
              phone: '7326426722'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: string
              example: Successful
          headers: {}
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorInfo'
              example:
                id: '400'
                message: Invalid email
          headers: {}
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorInfo'
              example:
                id: '401'
                message: Unauthorized
          headers: {}
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorInfo'
              example:
                id: '404'
                message: User not found
          headers: {}
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorInfo'
              example:
                id: '1000'
                message: Internal Server Error
          headers: {}
      security:
        - bearer: []
  /user/account/cancel/{userid}:
    delete:
      summary: Cancel User
      deprecated: false
      description: >-
        This API cancels the user's offer, and the partner will not be billed.
        Include a unique Idempotency-Key header to prevent duplicate
        cancellations. Use the header Version: v2 to enable idempotency and
        ensure synchronous API execution.
      tags: []
      parameters:
        - name: userid
          in: path
          description: This field represents the user’s ID in the partner’s system.
          required: true
          schema:
            type: string
        - name: Idempotency-Key
          in: header
          description: ''
          required: true
          example: ''
          schema:
            type: string
        - name: Version
          in: header
          description: ''
          required: true
          example: ''
          schema:
            type: string
        - name: x-api-key
          in: header
          description: ''
          required: false
          example: ''
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: string
              example: Successful
          headers: {}
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorInfo'
              example:
                id: '1007'
                message: ''
          headers: {}
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorInfo'
              example:
                id: '401'
                message: Unauthorized
          headers: {}
      security:
        - bearer: []
  /user/prefill:
    post:
      summary: Prefil User
      deprecated: false
      description: >-
        Allows prefill data to capture through api and prefill it on
        registration page. Include a unique Idempotency-Key (usually hash of
        request body) header. If same idempotency key comes in header and
        prefill exists with that request, response will be 409 - user exists
        already. if new idempotent key come then api will create or update
        existing entry. Use the header Version: v2 to enable idempotency and
        ensure synchronous API execution.
      tags: []
      parameters:
        - name: Content-Type
          in: header
          description: ''
          required: true
          example: application/json
          schema:
            type: string
        - name: Idempotency-Key
          in: header
          description: ''
          required: true
          example: ''
          schema:
            type: string
        - name: Version
          in: header
          description: ''
          required: true
          example: ''
          schema:
            type: string
        - name: x-api-key
          in: header
          description: ''
          required: false
          example: ''
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/prefillInfo'
            example:
              - firstname: Ivah
                lastname: Stokes
                email: abc123@yahoo.com
                zipcode: '08830'
                dob: '2022-01-02'
                userid: '{{userid}}'
                phone: '7326921234'
                gender: M
                address:
                  addline1: 143 bond street
                  addline2: ''
                  addline3: ''
                  city: iselin
                  state: NJ
                  zipcode: '08830'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: string
              example: Successful
          headers: {}
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorInfo'
              example:
                id: '400'
                message: Invalid email
          headers: {}
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorInfo'
              example:
                id: '401'
                message: Unauthorized
          headers: {}
        '409':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorInfo'
              example:
                id: '409'
                message: User exists already
          headers: {}
      security:
        - bearer: []
  /oauth2/token:
    post:
      summary: Authentication API
      deprecated: false
      description: >-
        Avibra uses the OAuth 2.0 Client Credentials Grant flow to obtain an
        access_token, which is then used to make REST API calls.
      tags: []
      parameters:
        - name: Content-Type
          in: header
          description: ''
          required: true
          example: application/x-www-form-urlencoded
          schema:
            type: string
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  example: client_credentials
                  type: string
                client_id:
                  example: '{{clientId}}'
                  type: string
                client_secret:
                  example: '{{clientSecret}}'
                  type: string
                scope:
                  example: '{{scope}}'
                  type: string
              required:
                - grant_type
                - client_id
                - client_secret
                - scope
            examples: {}
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/accesstokenInfo'
              example:
                access_token: ''
                expires_in: 0
                token_type: Bearer
          headers: {}
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: error message
                    examples:
                      - ''
                required:
                  - error
              example:
                error: invalid_client
          headers: {}
      security: []
  /user/linktoken3:
    post:
      summary: LinkToken API
      deprecated: false
      description: >-
        This API returns linktoken specific to user which can be appened to
        portal url (linktoken param).This token secures portal url. Api requires
        basic auth to authenticate. Username and Password will be provided by
        Avibra
      tags: []
      parameters:
        - name: Content-Type
          in: header
          description: ''
          required: true
          example: application/json
          schema:
            type: string
        - name: x-api-key
          in: header
          description: ''
          required: false
          example: ''
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/linktokenInfo'
            examples:
              '1':
                value:
                  partnerprofileid: '{{partnerprofileid}}'
                  userid: '{{userid}}'
                summary: Valid Request
              '2':
                value:
                  partnerprofileid: ''
                  userid: '{{userid}}'
                summary: Invalid Request
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/linktokenesponseInfo'
              example:
                linktoken: link-25223fa8-c53a-4dec-9940-aea0c8de3a60
                expiresat: '2025-04-09T21:52:55.326Z'
          headers: {}
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorInfo'
              example:
                id: '400'
                message: Missing partner profile ID
          headers: {}
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorInfo'
              example:
                id: '401'
                message: Unauthorized
          headers: {}
      security:
        - basic: []
  /user/benefits:
    post:
      summary: Get Benefits With Status
      deprecated: false
      description: ''
      tags: []
      parameters:
        - name: Content-Type
          in: header
          description: ''
          required: true
          example: application/json
          schema:
            type: string
        - name: x-api-key
          in: header
          description: ''
          required: false
          example: ''
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/getbenefitInfo'
            example:
              userid: '{{userid}}'
              age: 45
              state: NJ
              zipcode: '08830'
              partnername: '{{partnername}}'
              offername: '{{offername}}'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/benefitwithstatusInfos'
              examples:
                '1':
                  summary: Before Onboarding
                  value:
                    - name: ci
                      displayname: Critical Illness Benefits
                      icon: https://icons.avibra.com/2.5K+Critical+Illnes_icon.png
                      description: Fixed lump-sum cash benefit for covered illnesses.
                      status: notenrolled
                      benefittype: dollar
                      deeplinkdata: >-
                        &productname=ci&producttype=dobs&redirectto=drilldown-details
                      isselectedforswap: false
                      swapeffectiveattimestamp: null
                      swapexpiresattimestamp: null
                    - name: adnd
                      displayname: Accidental Death Insurance
                      icon: https://icons.avibra.com/20KADND.png
                      description: >-
                        Emergency cash for you or your loved ones after a major
                        accident.
                      status: notenrolled
                      benefittype: dollar
                      deeplinkdata: >-
                        &productname=adnd&producttype=dobs&redirectto=drilldown-details
                      isselectedforswap: null
                      swapeffectiveattimestamp: null
                      swapexpiresattimestamp: null
                    - name: life
                      displayname: $1,000 Life Insurance
                      icon: https://icons.avibra.com/5000LifeInsurance.png
                      description: >-
                        Lump-sum cash benefit for your loved ones in the event
                        of your death.
                      status: enrolled
                      benefittype: dollar
                      deeplinkdata: >-
                        &productname=life&producttype=dobs&redirectto=drilldown-details
                      isselectedforswap: null
                      swapeffectiveattimestamp: null
                      swapexpiresattimestamp: null
                '2':
                  summary: After Onboarding
                  value:
                    - name: ci
                      displayname: Critical Illness Benefits
                      icon: https://icons.avibra.com/2.5K+Critical+Illnes_icon.png
                      description: Fixed lump-sum cash benefit for covered illnesses.
                      status: notenrolled
                      benefittype: dollar
                      deeplinkdata: >-
                        &productname=ci&producttype=dobs&redirectto=drilldown-details
                      isselectedforswap: true
                      swapeffectiveattimestamp: '1748736000'
                      swapexpiresattimestamp: null
                    - name: adnd
                      displayname: Accidental Death Insurance
                      icon: https://icons.avibra.com/20KADND.png
                      description: >-
                        Emergency cash for you or your loved ones after a major
                        accident.
                      status: notenrolled
                      benefittype: dollar
                      deeplinkdata: >-
                        &productname=adnd&producttype=dobs&redirectto=drilldown-details
                      isselectedforswap: null
                      swapeffectiveattimestamp: null
                      swapexpiresattimestamp: null
                    - name: life
                      displayname: $1,000 Life Insurance
                      icon: https://icons.avibra.com/5000LifeInsurance.png
                      description: >-
                        Lump-sum cash benefit for your loved ones in the event
                        of your death.
                      status: enrolled
                      benefittype: dollar
                      deeplinkdata: >-
                        &productname=life&producttype=dobs&redirectto=drilldown-details
                      isselectedforswap: true
                      swapeffectiveattimestamp: null
                      swapexpiresattimestamp: '1748735999'
          headers: {}
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorInfo'
              example:
                id: '400'
                message: Invalid email
          headers: {}
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorInfo'
              example:
                id: '401'
                message: Unauthorized
          headers: {}
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorInfo'
              example:
                id: '404'
                message: User Not Found
          headers: {}
      security:
        - bearer: []
  /partnerwebhookurl:
    post:
      summary: Webhook API (provided by partner)
      deprecated: false
      description: ''
      tags: []
      parameters:
        - name: Content-Type
          in: header
          description: ''
          required: true
          example: application/json
          schema:
            type: string
        - name: Idempotency-Key
          in: header
          description: ''
          required: false
          example: '{{$string.uuid}}'
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/eventInfo'
            examples:
              '1':
                value:
                  userid: ''
                  eventname: offer_activiation_successful
                  currentofferdetails:
                    offer: '{{offername}}'
                    updatedat: '2021-01-01T15:29:53.744Z'
                    avibraid: ''
                summary: Example
              '2':
                value:
                  eventname: user_benefits_pendingswap
                  userid: cu62
                  currentofferdetails:
                    offer: elite
                    updatedat: '2025-05-23T09:03:39.487Z'
                    avibraid: null
                  moredetails:
                    - key: benefits
                      value: adnd
                summary: Pending Swap
              '3':
                value:
                  eventname: user_benefits_swapped
                  userid: cu62
                  currentofferdetails:
                    offer: elite
                    updatedat: '2025-05-23T09:44:16.502Z'
                    avibraid: null
                  moredetails:
                    - key: benefits
                      value: adnd
                summary: Swaped
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - type: string
                  - type: object
                    properties: {}
                  - type: integer
          headers: {}
      security:
        - basic: []
webhooks: {}
components:
  schemas:
    eventInfo:
      type: object
      properties:
        userid:
          type: string
          description: >-
            This field represents the user’s ID in the partner’s system. While
            it is an important identifier.
        eventname:
          type: string
          enum:
            - enrollment_request_received
            - enrollment_successful
            - offer_activiation_successful
            - offer_upgrade_successful
            - offer_downgrade_successful
            - offer_removal_successful
            - offer_error_processing
          description: Event name
        currentofferdetails:
          $ref: '#/components/schemas/currentofferdetailsInfo'
        moredetails:
          $ref: '#/components/schemas/moredetails'
      required:
        - userid
        - eventname
    userInfo:
      type: object
      properties:
        firstname:
          type: string
          description: First name of user
        lastname:
          type: string
          description: Last name of user
        email:
          type: string
          description: A valid email
          format: email
        zipcode:
          type: string
          description: Valid USA zipcode
          examples:
            - '08830'
          minLength: 5
          maxLength: 5
          pattern: ^\d{5}
        dob:
          type: string
          description: User should be above 18
          format: date
          examples:
            - '2022-01-02'
          pattern: yyyy-mm-dd
        partneroffer:
          type: string
          description: >-
            An partneroffer is a predetermined bundle of benefits agreed upon by
            the partner and Avibra. Offer names are finalized collaboratively by
            Avibra and the partner.
        userid:
          type: string
          description: This field represents the user’s ID in the partner’s system.
        phone:
          type: string
          description: 10 digit USA valid Phone number
          minLength: 10
          maxLength: 10
          examples:
            - '7326921234'
          pattern: ^\d{10}
        gender:
          type: string
          description: M - Male, F - Female, Send empty if not available
          examples:
            - M
            - F
          enum:
            - M
            - F
        address:
          $ref: '#/components/schemas/addressInfo'
          description: Residential address of user
        benefits:
          type: array
          items:
            type: string
          description: >-
            Premium benefits will be assigned to the user upon successful
            account creation. Benefits name can be retreived through Get
            Benefits With Status   API
      required:
        - firstname
        - lastname
        - email
        - zipcode
        - dob
        - phone
        - gender
        - userid
        - address
    addressInfo:
      type: object
      properties:
        addline1:
          type: string
        addline2:
          type: string
        addline3:
          type: string
        city:
          type: string
        state:
          type: string
        zipcode:
          type: string
      required:
        - addline1
        - city
        - state
        - zipcode
    benefitwithstatusInfo:
      type: object
      properties:
        name:
          type: string
          description: Benefit Key
        displayname:
          type: string
          description: Benefit Display Name
        icon:
          type: string
          description: Icon Url
          format: uri
        description:
          type: string
          description: Benefit Short Description
        status:
          type: string
          description: Status of benefit with regards to user - enrolled / notenrolled
          enum:
            - enrolled
            - notenrolled
        benefittype:
          type: string
          description: basic (core) or premium (dollar)
          enum:
            - core
            - dollar
          examples:
            - core
        deeplinkdata:
          type: string
          description: >
            deeplink part to be attached to portal link to launch details screen
            of benefits once benefit is enrolled.
        isselectedforswap:
          type:
            - boolean
            - 'null'
          description: set to true if benefit is selected for swap for next month
        swapeffectiveattimestamp:
          type:
            - string
            - 'null'
          description: >-
            if benefit is selected for swap, then it will show when that benefit
            will swap. it is epoach timestamp in string format
        swapexpiresattimestamp:
          type:
            - string
            - 'null'
          description: >-
            if benefit is removed in swap, then it will show when that benefit
            will removed. it is epoach timestamp in string format
    benefitwithstatusInfos:
      type: array
      items:
        $ref: '#/components/schemas/benefitwithstatusInfo'
    errorInfo:
      type: object
      properties:
        id:
          type: string
          description: ID
        message:
          type: string
          description: Error Message
        userid:
          type: string
      required:
        - message
    updateuserInfo:
      type: object
      properties:
        userid:
          type: string
          description: This field represents the user’s ID in the partner’s system.
        firstname:
          type: string
          description: First name of user. emply field is not consider for update
        lastname:
          type: string
          description: Last name of user. emply field is not consider for update
        email:
          type: string
          format: email
          examples:
            - example@email.com
          description: A Valid Email. emply field is not consider for update
        phone:
          type: string
          description: A Valid 10 digit number. emply field is not consider for update
          minLength: 10
          maxLength: 10
          pattern: ^\d{10}
          examples:
            - '7326921234'
        partnername:
          type: string
          description: 'partnername provided by avibra. '
      required:
        - userid
        - partnername
    linktokenInfo:
      type: object
      properties:
        partnerprofileid:
          type: string
          description: this key will be provided by Avibra and should be secured
          format: guid
        userid:
          type: string
          description: this key identify user unqiuely in partner system.
          format: string
    linktokenesponseInfo:
      type: object
      properties:
        linktoken:
          type: string
          description: string starts with 'link-'
        expiresat:
          type: string
      required:
        - linktoken
        - expiresat
    accesstokenInfo:
      type: object
      properties:
        access_token:
          type: string
        expires_in:
          type: integer
        token_type:
          type: string
      required:
        - access_token
        - expires_in
        - token_type
    getbenefitInfo:
      type: object
      properties:
        userid:
          type: string
          description: >-
            This field represents the user’s ID in the partner’s system. While
            it is an important identifier, it is optional.
        age:
          type: integer
          description: Age of user
          format: int32
          minimum: 18
          maximum: 100
        state:
          type: string
          description: Valid US State Abberivations
        zipcode:
          type: string
          description: 5 digit valid USA zipcode
          minLength: 5
          maxLength: 5
          pattern: ^\d{5}
          examples:
            - '08830'
        partnername:
          type: string
          description: partnername will be provided by Avibra
        offername:
          type: string
      required:
        - age
        - partnername
    offerInfo:
      type: object
      properties:
        userid:
          type: string
          description: This field represents the user’s ID in the partner’s system.
        offers:
          $ref: '#/components/schemas/offers'
    offers:
      type: array
      items:
        type: string
        description: >
          An offer is a predetermined bundle of benefits agreed upon by the
          partner and Avibra. Offer names are finalized collaboratively by
          Avibra and the partner.
        examples:
          - starter
          - elite
          - 1kinsurance
    offerInfos:
      type: array
      items:
        $ref: '#/components/schemas/offerInfo'
    currentofferdetailsInfo:
      type: object
      properties:
        offer:
          type: string
          description: >-
            User current offer. An offer is a predetermined bundle of benefits
            agreed upon by the partner and Avibra. Offer names are finalized
            collaboratively by Avibra and the partner.
          examples:
            - starter
            - elite
        updatedat:
          type: string
          format: date-time
          examples:
            - '2021-01-01T15:29:53.744Z'
          description: Event date and time
        avibraid:
          type: string
          description: User Unique Id in Avibra Ecosystem
          format: uuid
      required:
        - offer
        - updatedat
    moredetail:
      type: object
      properties:
        key:
          type: string
        value:
          type: string
      required:
        - key
        - value
    moredetails:
      type: array
      items:
        $ref: '#/components/schemas/moredetail'
    prefillInfo:
      type: object
      properties:
        firstname:
          type: string
          description: First name of user
        lastname:
          type: string
          description: Last name of user
        email:
          type: string
          description: A valid email
          format: email
        zipcode:
          type: string
          description: Valid USA zipcode
          examples:
            - '08830'
          minLength: 5
          maxLength: 5
          pattern: ^\d{5}
        dob:
          type: string
          description: User should be above 18
          format: date
          examples:
            - '2022-01-02'
          pattern: yyyy-mm-dd
        userid:
          type: string
          description: This field represents the user’s ID in the partner’s system.
        phone:
          type: string
          description: 10 digit USA valid Phone number
          minLength: 10
          maxLength: 10
          examples:
            - '7326921234'
          pattern: ^\d{10}
        gender:
          type: string
          description: M - Male, F - Female, Send empty if not available
          examples:
            - M
            - F
          enum:
            - M
            - F
        address:
          $ref: '#/components/schemas/addressInfo'
          description: Optional Address
      required:
        - email
        - userid
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
    basic:
      type: http
      scheme: basic
servers:
  - url: https://dev.avibra.com/preprod
    description: Testing Env
security: []
