Talkable Shares API

openapi: 3.0.3
info:
  title: Talkable Advocate Offers Shares API
  version: '2.0'
  contact:
    name: API Reference
    url: https://docs.talkable.com/api_v2/
servers:
- url: https://www.talkable.com
security:
- api_key: []
tags:
- name: Shares
paths:
  /api/v2/offer_claims:
    post:
      summary: Share and claim an offer
      tags:
      - Shares
      parameters:
      - $ref: '#/components/parameters/site_slug_in_query_required'
      - name: advocate_email
        in: query
        schema:
          type: string
          format: email
          example: advocate@example.com
        required: true
      - name: friend_email
        in: query
        schema:
          type: string
          format: email
          example: friend@example.com
        required: true
      operationId: shareAndClaimOffer
      responses:
        '200':
          description: null
          content:
            application/json:
              examples:
                friend rewarded:
                  value:
                    ok: true
                    result:
                      friend_reward:
                        amount: 10.0
                        id: 1
                        reason: click
                        status: Paid
                        coupon:
                          amount: 10.0
                          description: $10
                          code: COUPON_CODE_29
                          expires_at: null
                          id: 1
                          percentage_discount: false
                          single_use: true
                          used: false
                          active: true
                          usages: 0
                          valid_until: null
                        coupon_code: COUPON_CODE_29
                        incentive_type: discount_coupon
                        incentive_description: single use coupon for $10 off
                        incentive_custom_description: null
                      friend_unredeem_reason: null
                      friend_human_unredeem_reason: null
                friend not rewarded:
                  value:
                    ok: true
                    result:
                      friend_reward: null
                      friend_unredeem_reason: SELF_REFERRAL
                      friend_human_unredeem_reason: Self Referral
        '400':
          description: null
          content:
            application/json:
              examples:
                invalid email for Advocate:
                  value:
                    ok: false
                    error_message: Invalid `advocate_email`.
                invalid email for Friend:
                  value:
                    ok: false
                    error_message: Invalid `friend_email`.
                no campaign found:
                  value:
                    ok: false
                    error_message: No campaign found.
  /api/v2/people/{person_slug}/shares_by:
    parameters:
    - name: person_slug
      in: path
      schema:
        $ref: '#/components/schemas/person_slug'
      required: true
    get:
      summary: Get shares made by person
      description: Returns shares that person made.
      tags:
      - Shares
      parameters:
      - $ref: '#/components/parameters/site_slug_in_query_required'
      operationId: getSharesMadeByPerson
      responses:
        '200':
          description: person found
          content:
            application/json:
              example:
                ok: true
                result:
                  shares:
                  - shared_at: '2026-07-07T11:07:26.000-07:00'
                    short_url: https://share.my-store.com/x/HZRpFC
                    channel_identifier: facebook
                    id: 1
                    type: SocialOfferShare
                    offer:
                      claim_url: https://share.my-store.com/x/GbnMfD
                      email: customer@example.com
                      id: 1
                      short_url_code: dy8h95
                      show_url: https://share.my-store.com/x/8tp5sj
                      coupon_code: null
                      incentives:
                        referrer:
                          action_type: referrer
                          amount: 10.0
                          description: $10
                          percentage: false
                          criteria_config:
                            new_customer: null
                            new_optin: false
                            subtotal_min: null
                            subtotal_max: null
                            referrals_min: null
                            referrals_max: null
                            referrals_divisible_by: null
                            referrals_not_divisible_by: null
                            reward_uniqueness: once_per_friend
                            friend_event_category: null
                            has_liquid_criteria: false
                          for_advocate: true
                          for_friend: false
                          highest_amount: true
                          identifier: referrer
                          incentive_type: discount_coupon
                          coupon_expires_at: null
                      trigger_widget: false
                      campaign_tags: []
                    campaign:
                      slug: 1
                      is_active: true
                      appearance: inline
                      id: 1
                      joinable_category_names:
                      - affiliate_member
                      name: Deal for friends
                      origin_max_age: null
                      origin_min_age: null
                      status: Live
                      tag_names: []
                      live_period:
                        starts_at: '2026-07-07T11:07:00.000-07:00'
                        ends_at: null
                    friends_count: 0
                    friend_clicks_count: 0
                  - shared_at: '2026-07-07T11:07:26.000-07:00'
                    short_url: https://share.my-store.com/x/cNjpnJ
                    channel_identifier: email
                    id: 2
                    type: EmailOfferShare
                    email: test+62@example.com
                    offer:
                      claim_url: https://share.my-store.com/x/GbnMfD
                      email: customer@example.com
                      id: 1
                      short_url_code: dy8h95
                      show_url: https://share.my-store.com/x/8tp5sj
                      coupon_code: null
                      incentives:
                        referrer:
                          action_type: referrer
                          amount: 10.0
                          description: $10
                          percentage: false
                          criteria_config:
                            new_customer: null
                            new_optin: false
                            subtotal_min: null
                            subtotal_max: null
                            referrals_min: null
                            referrals_max: null
                            referrals_divisible_by: null
                            referrals_not_divisible_by: null
                            reward_uniqueness: once_per_friend
                            friend_event_category: null
                            has_liquid_criteria: false
                          for_advocate: true
                          for_friend: false
                          highest_amount: true
                          identifier: referrer
                          incentive_type: discount_coupon
                          coupon_expires_at: null
                      trigger_widget: false
                      campaign_tags: []
                    campaign:
                      slug: 1
                      is_active: true
                      appearance: inline
                      id: 1
                      joinable_category_names:
                      - affiliate_member
                      name: Deal for friends
                      origin_max_age: null
                      origin_min_age: null
                      status: Live
                      tag_names: []
                      live_period:
                        starts_at: '2026-07-07T11:07:00.000-07:00'
                        ends_at: null
                    friends_count: 0
                    friend_clicks_count: 0
        '400':
          description: person not found
          content:
            application/json:
              example:
                ok: false
                error_message: No person found by `person_slug`.
  /api/v2/offers/{short_url_code}/shares/email:
    post:
      summary: Share offer with recipients via email
      operationId: shareViaEmail
      tags:
      - Shares
      parameters:
      - name: short_url_code
        in: path
        schema:
          type: string
        required: true
      responses:
        '200':
          description: sends offer to recipients
          content:
            application/json:
              example:
                ok: true
                result:
                  success: true
                  validation_only: false
                  stats:
                    currently_sent: 3
                    currently_not_sent: 0
                    previously_sent: 0
                    total_sent: 3
                    sent_limit_exceeded: false
                    left_emails: 22
                    advocate_blocked: false
                  recipients:
                    recipient_1@com.com:
                      currently_sent: true
                      previously_sent: false
                      email_valid: true
                      self_referral: false
                      unsubscribed: false
                      blocklisted: false
                      blacklisted: false
                      meets_criteria: true
                      sharable: true
                    recipient_2@com.com:
                      currently_sent: true
                      previously_sent: false
                      email_valid: true
                      self_referral: false
                      unsubscribed: false
                      blocklisted: false
                      blacklisted: false
                      meets_criteria: true
                      sharable: true
                    recipient_3@com.com:
                      currently_sent: true
                      previously_sent: false
                      email_valid: true
                      self_referral: false
                      unsubscribed: false
                      blocklisted: false
                      blacklisted: false
                      meets_criteria: true
                      sharable: true
                  reward: null
                  rewards: []
        '400':
          description: returns bad request when missing recipients
          content:
            application/json:
              example:
                ok: false
                error_message: '`recipients` is required'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                reminder:
                  type: boolean
                  example: true
                validation_only:
                  type: boolean
                  example: false
                recipients:
                  type: string
                  example: recipient_1@com.com,recipient_2@com.com,recipient_3@com.com
                subject:
                  type: string
                  example: Your friend sent you x% off
                body:
                  type: string
                  example: Your personal message with offer link
              required:
              - recipients
  /api/v2/offers/{short_url_code}/shares/social:
    post:
      summary: Share offer with recipients via social channel
      operationId: shareViaSocialChannel
      tags:
      - Shares
      parameters:
      - name: short_url_code
        in: path
        schema:
          type: string
        required: true
      responses:
        '200':
          description: share offer to social channel
          content:
            application/json:
              example:
                ok: true
                result:
                  share:
                    shared_at: '2026-07-07T11:08:32.000-07:00'
                    short_url: https://share.my-store.com/x/IyfKJR
                    channel_identifier: facebook
                    id: 1
                    type: SocialOfferShare
                    offer:
                      claim_url: https://share.my-store.com/x/0iqOMr
                      email: signup18@example.com
                      id: 1
                      short_url_code: d3BGIz
                      show_url: https://share.my-store.com/x/Kg4GH7
                      coupon_code: C1383-8321
                      incentives:
                        sharing:
                          action_type: sharing
                          amount: 10.0
                          description: $10
                          percentage: false
                          criteria_config:
                            once_per_person: false
                            email_shares: null
                            sharing_channels: null
                            has_liquid_criteria: false
                          for_advocate: true
                          for_friend: false
                          highest_amount: true
                          identifier: sharing
                          incentive_type: discount_coupon
                          coupon_expires_at: null
                      trigger_widget: false
                      campaign_tags: []
                    campaign:
                      slug: 1
                      is_active: true
                      appearance: inline
                      id: 1
                      joinable_category_names:
                      - affiliate_member
                      name: Deal for friends
                      origin_max_age: null
                      origin_min_age: null
                      status: Live
                      tag_names: []
                      live_period:
                        starts_at: '2026-07-07T11:08:00.000-07:00'
                        ends_at: null
                    friends_count: 0
                    friend_clicks_count: 0
                  reward:
                    amount: 10.0
                    id: 1
                    reason: shared
                    status: Paid
                    coupon:
                      amount: 10.0
                      description: $10
                      code: C1383-8321
                      expires_at: null
                      id: 1
                      percentage_discount: null
                      single_use: false
                      used: false
                      active: true
                      usages: null
                      valid_until: null
                    coupon_code: C1383-8321
                    incentive_type: discount_coupon
                    incentive_description: shared coupon "C1383-8321" for $10 off
                    incentive_custom_description: null
        '400':
          description: returns bad request in the case of wrong social channel name
          content:
            application/json:
              example:
                ok: false
                error_message: '`channel` is invalid'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                channel:
                  type: string
                  enum:
                  - facebook
                  - twitter
                  - linkedin
                  - whatsapp
                  - sms
                  - other
                  example: facebook
              required:
              - channel
components:
  schemas:
    person_slug:
      type: string
      example: customer@example.com
      description: Person’s email, phone number, customer ID or username
  parameters:
    site_slug_in_query_required:
      name: site_slug
      in: query
      required: true
      schema:
        type: string
      description: Your Talkable Site ID. You can get this from your Talkable dashboard after you log in and create a site.
      example: my-store
  securitySchemes:
    api_key:
      type: http
      scheme: bearer
      description: Please provide here your API key, you can find it in Site Settings -> API Integration -> API Key