openapi: 3.1.0
info:
  title: Refer a Friend V3 APIs
  description: >-
    Thank you for choosing our Refer a Friend API to enhance your application's
    referral capabilities. This comprehensive documentation is designed to guide
    you through the seamless integration of our powerful referral system into
    your platform, allowing your users to effortlessly refer friends and unlock
    a world of rewards. Our team is committed to providing excellent developer
    support, so if you encounter any challenges or have any questions, please
    don't hesitate to reach out to us. We want to ensure that your experience
    with the Refer a Friend API is seamless and successful. So, let's get
    started and unlock the full potential of referral marketing together. A
    detailed explanation of the Refer a Friend User API and the examples are
    shown below.
  version: 3.0.1
servers:
  - url: https://s15.socialannex.net/api/3.0
paths:
  /createuser/{{siteId}}?access_token={{access_token}}:
    post:
      tags:
        - User
      summary: Create a new user account under a specific site
      description: >-
        This POST endpoint allows you to create a new user account under a
        specific site.
      operationId: InvitecodeCoupon
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                site_Id:
                  description: >-
                    Enter an identifier for the specific site. It is a unique
                    numerical code assigned to each site provided by Annex
                    Cloud.
                  example: '123456'
                  type: string
                access_token:
                  description: Enter the access token provided by Annex Cloud.
                  type: string
                  example: vsdhsvdj5555dd
                invite_code:
                  description: >-
                    Enter the code used for inviting members to join the
                    platform.
                  type: string
                  example: cfd55ss
                sa_stat_id:
                  description: >-
                    Enter the statistical tracking ID of the member who is
                    referring a friend. This ID is provided by Annex Cloud. This
                    ID is created when the member shares the referral code with
                    a friend. This ID is linked to the referral code.
                  example: 54465
                  type: integer
                friendEmail:
                  description: Enter the email address of the referree.
                  type: string
                  example: user@gmail.com
                incentive_id:
                  description: >-
                    Enter an identifier for the specific  Refer a Friend
                    campaign incentive. It is used to track and manage
                    incentives. Annex Cloud will provide Incentive ID.
                  example: '55599'
                  type: string
              required:
                - site_Id
                - access_token
                - invite_code
                - friendEmail
                - incentive_id
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/createuser'
            application/xml:
              schema:
                $ref: '#/components/schemas/createuser'
  /Createbitly/{{siteId}}?access_token={{access_token}}:
    post:
      tags:
        - Refer
      summary: Create bitly links
      description: >-
        This API is used to create bitly links for specific member’s Facebook,
        Twitter, and Email Sharing.
      operationId: createbitly
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                site_Id:
                  description: >-
                    Enter the unique identifier for the specific site. It is a
                    unique numerical code assigned to each site provided by
                    Annex Cloud.
                  example: '123456'
                  type: string
                access_token:
                  description: Enter the access token provided by Annex Cloud.
                  type: string
                  example: hgt45dg
                user_id:
                  description: Enter the unique identifier for the member.
                  type: string
                  example: '1234'
                incentive_id:
                  description: >-
                    Enter an identifier for the specific incentive provided by
                    the Annex Cloud. It is used to track and manage incentives.
                  example: 456
                  type: integer
                socialType:
                  description: >-
                    Enter the value 1 for Facebook Bitly, 2 for Twitter Bitly, 4
                    for Email Bitly.
                  type: integer
                  example: 1
              required:
                - site_Id
                - access_token
                - user_id
                - incentive_id
                - socialType
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/createbitly'
            application/xml:
              schema:
                $ref: '#/components/schemas/createbitly'
  /Referralstatus/{{siteId}}?access_token={{access_token}}:
    post:
      tags:
        - User
      summary: Get referral status
      description: >-
        This API is used to get the referral status of the referee (the friend
        who was referred by a member).
      operationId: invitecode
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                site_Id:
                  description: >-
                    Enter an identifier of the specific site. It is a unique
                    numerical code assigned to each site provided by Annex
                    Cloud.
                  example: '123456'
                  type: string
                access_token:
                  description: Enter the access token provided by Annex Cloud.
                  type: string
                  example: hgt45dg
                user_id:
                  description: Enter the unique identifier of the member.
                  type: string
                  example: '1234'
                incentive_id:
                  description: >-
                    Enter an identifier for the specific incentive provided by
                    the Annex Cloud. It is used to track and manage incentives.
                  example: 34567
                  type: integer
              required:
                - site_Id
                - access_token
                - user_id
                - incentive_id
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/userDetails'
            application/xml:
              schema:
                $ref: '#/components/schemas/userDetails'
  /Invitecodecoupon/{{siteId}}?access_token={{access_token}}:
    post:
      tags:
        - User
      summary: Create or Assign a new invite code coupon for a specific site
      description: This API is used to unlock the coupon code for the referee/friend.
      operationId: InvitecodeCoupon
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                site_Id:
                  description: >-
                    Enter an identifier for the specific site. It is a unique
                    numerical code assigned to each site provided by Annex
                    Cloud.
                  example: '123456'
                  type: string
                access_token:
                  description: Enter the access token provided by Annex Cloud.
                  type: string
                  example: vsdhsvdj5555dd
                invite_code:
                  description: >-
                    Enter the code used for inviting members to join the
                    platform.
                  type: string
                  example: cfd55ss
                sa_stat_id:
                  description: >-
                    Enter the statistical tracking ID of the member who is
                    referring a friend. This ID is provided by Annex Cloud. This
                    ID is created when the member shares the referral code with
                    a friend. This ID is linked to the referral code.
                  example: 54465
                  type: integer
                friendEmail:
                  description: Enter the email address of the referree.
                  type: string
                  example: user@gmail.com
                incentive_id:
                  description: >-
                    Enter an identifier for the specific  Refer a Friend
                    campaign incentive. It is used to track and manage
                    incentives. Annex Cloud will provide Incentive ID.
                  example: '55599'
                  type: string
              required:
                - site_Id
                - access_token
                - invite_code
                - friendEmail
                - incentive_id
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/createuser'
            application/xml:
              schema:
                $ref: '#/components/schemas/createuser'
  /Sendemail/{{siteId}}?access_token={{access_token}}:
    post:
      tags:
        - Refer
      summary: Send e-mail to friends
      description: This API is used to trigger invitation emails to friends.
      operationId: referralStatus
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                site_Id:
                  description: >-
                    Enter an identifier of the specific site. It is a unique
                    numerical code assigned to each site provided by Annex
                    Cloud.
                  example: '123456'
                  type: string
                access_token:
                  description: Enter the access token provided by Annex Cloud.
                  type: string
                  example: hgt45dg
                user_id:
                  description: Enter the unique identifier of the member.
                  type: string
                  example: '1234'
                toEmail:
                  description: >-
                    Enter the email addresses of friends who should receive the
                    email invitation. You can add  upto 10 email addresses
                    separated by “,”.
                  type: string
                  example: >-
                    user@domain.com,
                    user1@domain1.com,user2@dmoin2.com,user3@domain3.com
                incentive_id:
                  description: >-
                    Enter an identifier for the specific incentive provided by
                    the Annex Cloud. It is used to track and manage incentives.
                  type: integer
                  example: 456
              required:
                - site_Id
                - access_token
                - user_id
                - toEmail
                - incentive_id
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/sendemailresp'
            application/xml:
              schema:
                $ref: '#/components/schemas/sendemailresp'
  /userinformation/{{siteId}}?access_token={{access_token}}:
    post:
      tags:
        - User
      summary: Retrive the sharer email address
      description: >-
        This API is used to get member information registered in the RAF module
        by providing an email address and incentive ID.
      operationId: getSharerEmail
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                site_Id:
                  description: >-
                    Enter an identifier for the specific site. It is a unique
                    numerical code assigned to each site provided by Annex
                    Cloud.
                  example: '123456'
                  type: string
                access_token:
                  description: Enter the access token provided by Annex Cloud.
                  type: string
                  example: vsdhsvdj5555dd
                email:
                  description: >-
                    Enter the email address of the member. Email addresses are
                    often used as unique identifiers for member accounts. If a
                    unique ID number is used to identify members for your
                    program, then the unique ID number is entered in this field
                    and the email is entered in the user_email field.
                  example: user@gmail.com
                  type: string
                incentive_id:
                  description: >-
                    Enter an identifier for the specific  Refer a Friend
                    campaign incentive. It is used to track and manage
                    incentives. Annex Cloud will provide Incentive ID.
                  example: 55599
                  type: integer
              required:
                - site_Id
                - access_token
                - email
                - incentive_id
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getSharerEmail'
            application/xml:
              schema:
                $ref: '#/components/schemas/getSharerEmail'
  /userinvitecodedetail/{{siteId}}?access_token={{access_token}}:
    post:
      tags:
        - User
      summary: Get referrer's details
      description: >-
        This API is used to get the referrer’s details through the stat ID and
        invite code.
      operationId: invitecodedetail
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                stat_id:
                  description: >-
                    Enter the referrer’s static identifier of the member who
                    shared the invite code to the friend.
                  example: 1234
                  type: integer
                invite_code:
                  description: >-
                    Enter the referrer’s personal invite code. The invite code
                    is provided to members to refer a friend.
                  example: '1234'
                  type: string
                access_token:
                  description: Enter the access token provided by Annex Cloud.
                  type: string
                  example: hgt45dg
              required:
                - access_token
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/invitecodedetailresp'
            application/xml:
              schema:
                $ref: '#/components/schemas/invitecodedetailresp'
  /Invitecodecoupon/{{site_id}}?access_token={{access_token}}:
    post:
      tags:
        - Reward
      summary: Generate a coupon code for an invitee using a referral invite code
      description: >-
        This endpoint is used to generate and assign a coupon code to a referred
        user (invitee) based on a valid referral invite code.
      operationId: invitecouponsiteidaccesstoken
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                site_id:
                  description: >-
                    Enter an identifier for the specific site. It is the unique
                    numerical code assigned to each site provided by Annex
                    Cloud.
                  example: '1234'
                  type: string
                access_token:
                  description: Enter the access token provided by Annex Cloud.
                  type: string
                  example: hgt45dg
                invite_code:
                  description: >-
                    Enter the referrer’s personal invite code. The invite code
                    is provided to members to refer a friend.
                  example: '1234'
                  type: string
                sa_stat_id:
                  description: >-
                    Enter the referrer’s static identifier of the member who
                    shared the invite code to the friend.
                  type: integer
                  example: 1234
                friend_email:
                  description: >-
                    Enter the email address of the referred friend to associate
                    them with the referral process.
                  example: xyz@gmail.com
                  type: string
                incentive_id:
                  description: >-
                    Enter an identifier for the specific incentive provided by
                    the Annex Cloud. It is used to track and manage incentives.
                  example: hgt45dg
                  type: string
              required:
                - site_id
                - access_token
                - invite_code
                - friend_email
                - incentive_id
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/invitecouponsiteidaccesstokenresp'
            application/xml:
              schema:
                $ref: '#/components/schemas/invitecouponsiteidaccesstokenresp'
components:
  schemas:
    createuser:
      type: object
      properties:
        status:
          type: string
          description: >-
            Displays the status of the API executed. If Success is shown then
            the API has executed successfully. If Failed is shown, then the API
            has failed to execute.
          example: Success
        data:
          type: object
          description: Displays the following details.
          properties:
            coupon_code:
              type: string
              description: Displays the coupon code.
              example: RKTKR
            message:
              type: string
              description: Displays the Success or failure message.
              example: Coupon Code Generated successfully
    createbitly:
      type: object
      properties:
        status:
          type: string
          description: >-
            Displays the status of the API executed. If Success is shown then
            the API has executed successfully. If Failed is shown, then the API
            has failed to execute.
          example: Success
        data:
          type: object
          properties:
            bitly:
              type: integer
              description: Displays the bitly link for the social type.
              example: https://bit.ly/3Bdfgfc
    invitecouponsiteidaccesstokenresp:
      type: object
      properties:
        status:
          type: string
          description: >-
            Displays the status of the API executed. If Success is shown then
            the API has executed successfully. If Failed is shown, then the API
            has failed to execute.
          example: Success
        data:
          type: object
          description: Displays the following details.
          properties:
            coupon_code:
              type: string
              description: Displays the coupon code.
              example: RKTKR
            message:
              type: string
              description: Displays the Success or failure message.
              example: Coupon Code Generated successfully
    userDetails:
      type: object
      properties:
        status:
          type: string
          description: >-
            Displays the status of the API executed. If Success is shown then
            the API has executed successfully. If Failed is shown, then the API
            has failed to execute.
          example: Success
        data:
          type: object
          properties:
            sharedata:
              type: object
              description: Displays the data regarding how the referral was shared
              properties:
                referral_settings:
                  type: object
                  description: Displays the data regarding the referral settings
                  properties:
                    refferal_status_col_email_address:
                      type: string
                      description: >-
                        Displays the reference field name, when the referral
                        status API gets the data, the email address field is
                        shown in the response.
                      example: Email Address
                    refferal_status_col_email_network:
                      type: string
                      description: >-
                        Displays the reference field name, when the referral
                        status API gets the data, the social type field is shown
                        in the response.
                      example: Network
                    refferal_status_col_status:
                      type: string
                      description: >-
                        Displays the reference field name, when the referral
                        status API gets the data, the status field is shown in
                        the response.
                      example: Status
                referral_status:
                  type: object
                  description: Displays the data regarding the referral status
                  properties:
                    email_address:
                      type: string
                      description: Displays the email address of the referee.
                      example: harrywhite21.sa@gmail.com
                    friend_fullname:
                      type: string
                      description: Displays the full name of the referee.
                      example: harry.sa
                    add_date:
                      type: string
                      description: >-
                        Displays the date and time when the referee became
                        registered as a member. The format of the date and time
                        is “yyyy-MM-dd'T'HH:mm:ss Z”.
                      example: '2022-08-01 07:31:32'
                    update_status_date:
                      type: string
                      description: >-
                        Displays the date and time when the referee’s status was
                        updated. The format of the date and time is
                        “yyyy-MM-dd'T'HH:mm:ss Z”.
                      example: '2022-08-01 07:31:32'
                    status:
                      type: string
                      description: >-
                        Displays the status of the referee as-Invite sent,
                        Waiting for purchase, or Purchased.
                      example: Invite sent
                    social_type:
                      type: string
                      description: >-
                        Displays in which social type the sharer has referred
                        the referee. For example- Twitter, Facebook, or copy
                        link.
                      example: Copy link
                    network_img:
                      type: string
                      description: >-
                        Displays the link for the logo of the social network in
                        which the sharer has referred the referee.
                      example: >-
                        https://admin.socialannexuat.com/assets/v1/media/logos/AC-logo.png
                    referral_purchase_count:
                      type: integer
                      description: >-
                        Displays the number of referral purchases if the referee
                        has made purchases with the brand.
                      example: 10
    sendemailresp:
      type: object
      properties:
        status:
          type: string
          description: >-
            Displays the status of the API executed. If Success is shown then
            the API has executed successfully. If Failed is shown, then the API
            has failed to execute.
          example: Success
        data:
          type: array
          description: >-
            Displays the data for email invitations sent to the email address
            mentioned in the request parameter “toemail” with the success
            message.
    getSharerEmail:
      type: object
      properties:
        status:
          type: string
          description: >-
            Displays the status of the API executed. If Success is shown then
            the API has executed successfully. If Failed is shown, then the API
            has failed to execute.
          example: Success
        data:
          type: object
          properties:
            userinfo:
              type: object
              properties:
                user_id:
                  type: string
                  description: >-
                    Displays the unique identifier for the member. It is a
                    unique numerical code assigned to each member. The user ID
                    is created in the RAF module for the member.
                  example: '12345'
                email_id:
                  type: string
                  description: >-
                    Displays the email address of a member. Email addresses are
                    often used as unique identifiers for member accounts.
                  example: user@domain.com
                first_name:
                  type: string
                  description: Displays the first name of the referred member.
                  example: john
                last_name:
                  type: string
                  description: Displays the last name of the referred member.
                  example: dee
                from_email:
                  type: string
                  description: Displays the referrer member email address.
                  example: dean@yahoo.com
                sharer_stat_id:
                  type: integer
                  description: >-
                    Displays the sharer static identifier of the member who
                    shared the invite code to the friend.
                  example: 1234
                default_personal_bitly:
                  type: string
                  description: Displays the members' personal data with bitly link.
                  example: https://bit.ly/3Bdfgfc
                personal_invite_code:
                  type: string
                  description: >-
                    Displays sharer’s personal invite code. The invite code is
                    provided to members to refer a friend.
                  example: f7BUBJ
                db_update_date:
                  type: string
                  description: >-
                    Displays the date when the member's information was last
                    updated in the database. The format of the date is
                    “YYYY-MM-DD“.
                  example: '2023-12-06'
                referer_id:
                  type: integer
                  description: >-
                    Displays the unique identifier of the referer who referred
                    the friend by the the invite code or bitly link.
                  example: 10203057
        account_info:
          type: object
          properties:
            db_add_data:
              type: string
              description: >-
                Displays the date when the member's information was added to the
                database (member registered date). The format of the date is
                “yyyy-MM-dd'T'HH:mm:ss Z”.
              example: 2021-02-09T18:27:35+0000
            db_update_date:
              type: string
              description: >-
                Displays the date when the member's information was updated in
                the database. The format of the date is “yyyy-MM-dd“.
              example: '2021-02-09'
            user_id:
              type: string
              description: >-
                Displays the unique identifier for the member. It is a unique
                numerical code assigned to each member. The user ID is created
                in the RAF module for the member.
              example: '1234'
            login__log:
              type: integer
              description: >-
                Displays the number of times the member has logged in to their
                account.
              example: 10
        activity_info:
          type: object
          properties:
            total_orders:
              type: integer
              description: Displays total number of orders placed by the member.
              example: 20
            revenue:
              type: integer
              description: Displays the total amount spent by the member.
              example: 1205
        order_details:
          type: object
          properties:
            order_id:
              type: integer
              description: Displays the order ID for the order placed by the member.
              example: 123456
            create_date:
              type: string
              description: >-
                Displays the date and time of the order placed by the member.
                The format of the date and time is “yyyy-MM-dd'T'HH:mm:ss Z”.
              example: 2021-02-09T18:27:35+0000
            order_amount:
              type: integer
              description: Displays the price of the order placed by the member.
              example: 56
        referral_program:
          type: object
          properties:
            sharing_details:
              type: object
              properties:
                facebook:
                  type: integer
                  description: >-
                    Displays the number of times the personal URL has been
                    shared via Facebook.
                  example: 12
                twitter:
                  type: integer
                  description: >-
                    Displays the number of times the personal URL has been
                    shared via Twitter.
                  example: 23
                email:
                  type: integer
                  description: >-
                    Displays the number of times the personal URL has been
                    shared via email.
                  example: 34
                personal_bitly:
                  type: integer
                  description: >-
                    Displays the number of times the referral bitly link has
                    been shared.
                  example: 45
                other:
                  type: integer
                  description: >-
                    Displays the number of times RAF invite code has been shared
                    by the member.
                  example: 56
        coupon_details:
          type: array
          description: >-
            Displays the member’s coupon codes details with status. If the
            member registers with the invite code sent by the referer, the
            member will get a coupon code.
        reward_details:
          type: array
          description: >-
            Displays reward details of a member who shared the invite code. The
            member has credit points to claim reward codes. the list of rewards
            claimed is displayed.
    invitecodedetailresp:
      type: object
      properties:
        status:
          type: string
          description: >-
            Displays the status of the API executed. If Success is shown then
            the API has executed successfully. If Failed is shown, then the API
            has failed to execute.
          example: Success
        data:
          type: object
          properties:
            user_email:
              type: string
              description: >-
                Displays the email address of the member who referred their
                friend.
              example: jacklee2023.sa1708222@gmail.com
            user_id:
              type: string
              description: >-
                Displays the unique identifier for the member. It is a unique
                numerical code assigned to each member. The user ID is created
                in the RAF module for the member.
              example: '1234'
            messages:
              type: string
              description: >-
                Displays the message Get user info successfully, if member
                information is successfully fetched.
              example: Get user info successfully
tags:
  - name: User
    description: >-
      Thank you for choosing our Refer a Friend API to enhance your
      application's referral capabilities. This comprehensive documentation is
      designed to guide you through the seamless integration of our powerful
      referral system into your platform, allowing your users to effortlessly
      refer friends and unlock a world of rewards. Our team is committed to
      providing excellent developer support, so if you encounter any challenges
      or have any questions, please don't hesitate to reach out to us. We want
      to ensure that your experience with the Refer a Friend API is seamless and
      successful. So, let's get started and unlock the full potential of
      referral marketing together. A detailed explanation of the Refer a Friend
      User API and the examples are shown below.
  - name: Refer
    description: >-
      Referral Marketing Program creates a channel for your customers to share
      your brand with their friends and family. From social media integration to
      email, and in-person recommendations you can proactively cultivate
      referrals anywhere, and comprehensive reporting helps you track and
      optimize your various referral channels. Most of the consumers trust
      recommendations from friends and family more than other forms of
      advertising. Refer a Friend enables you to organically grow your customer
      base by giving your loyal shoppers a platform to advocate for your brand.
      This API is used to send email invitations to members' friends and to get
      bitly against the specific social type (i.e., Facebook, Twitter & SMS
      sharing). A detailed explanation of RAF Refer API and the examples are
      shown below.
  - name: Reward
    description: >-
      Referral Marketing Program creates a channel for your customers to share
      your brand with their friends and family. From social media integration to
      email, and in-person recommendations you can proactively cultivate
      referrals anywhere, and comprehensive reporting helps you track and
      optimize your various referral channels. Customers who share your brand
      with their friends and family can earn good rewards. These rewards are in
      terms of various coupon codes and gift vouchers. This API is used to
      provide coupon codes, claim and manage earned rewards. A detailed
      explanation of RAF Reward API and the examples are shown below.
security:
  - MuseumPlaceholderAuth: []
