Playable Campaigns API

openapi: 3.2.0
info:
  title: Swagger with Laravel Campaigns API
  description: 'This documentation aims to provide all the information you need to work with our API.


    ***Rate limiting***


    APIs are bound by rate limiting. The default rate limiting allows for 3.600 API interactions an hour per developer app (not IP).

    You are **NOT** allowed to attempt by-pass of rate limiting by creating multiple apps and distribute your traffic across these.

    If an API has a different rate limit it will be described in the description of the API.


    ***Every API response contains 2 extra headers***

    1. `X-RateLimit-Limit` max number of requests you can do in the defined period.

    2. `X-RateLimit-Remaining` how many requests you have left before hitting the rate limit.


    ***Required Headers***

    1. `Authorization` used to provide credentials that authenticate an application.

    2. `Accept` specifies the response type. Only "application/json" is supported.


    Once you''ve hit your rate limit the response will also include `Retry-After`. This will be the seconds in which you will have to wait for doing additional API requests.


    ***Throughout***

    The API is designed to allow 3.600 requests per hour per developer app. This is a hard limit and cannot be increased.


    ***Caching***

    Playable *expect* implementations to be mindful of not overloading the API with requests.

    Playable **expect** implementations to cache data where possible and only request data when it''s needed.

    If you''re found to be abusing the API by not caching data, you may be subject to rate limiting or have your access revoked.

    '
  version: 1.0.0
servers:
- url: https://api.playable.com
  description: Production
- url: https://api.dev.playable.com
  description: QA
security:
- clientCredentials:
  - campaigns.list
  - campaigns.view
  - campaigns.pause
  - campaigns.resume
  - campaigns.activate
  - campaigns.integrations.list
  - campaigns.game-data-statistics
  - campaigns.game-settings.view
  - campaigns.game-settings.modify
  - campaigns.sections.list
  - campaigns.sections.view
  - campaigns.sections.form-fields.list
  - campaigns.sections.form-fields.view
  - campaigns.prizes.list
  - campaigns.prizes.view
  - campaigns.bulk-prizes.list
  - campaigns.bulk-prizes.view
  - campaigns.bulk-prizes.modify
  - campaigns.bulk-prizes-items.send-email
  - campaigns.email-log.list
  - campaigns.email-log.view
  - campaigns.sms-log.list
  - campaigns.sms-log.view
  - campaigns.registrations.list
  - campaigns.registrations.view
  - campaigns.registrations.delete
  - campaigns.voucher.list
  - campaigns.voucher.view
  - campaigns.voucher.delete
  - campaigns.types.list
  - campaigns.types.view
  - campaigns.copy
  - campaigns.modify
  - campaigns.delete
  - campaigns.clear-cache
  - media.upload
  - user.create-login-token
tags:
- name: campaigns
  description: Campaigns
paths:
  /v1/campaign-types:
    get:
      tags:
      - campaigns
      summary: Campaign types
      description: 'List all campaign types

        This API lists all campaign types in the system.


        Requires scope:


        `campaigns.types.list`

        '
      security:
      - clientCredentials:
        - campaigns.types.list
      parameters:
      - name: filter_category
        in: query
        description: 'Filter for campaign type category. Available options are: luck, skill, knowledge.'
        required: false
        schema:
          type: string
          enum:
          - luck
          - skill
          - knowledge
      responses:
        '200':
          description: Lists all campaign types available in the system
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
                          example: Quiz
                        alias:
                          type: string
                          example: quiz
                        variation:
                          type: string
                          example: GAME
                        description:
                          type: string
                        category:
                          type: string
                          example: Knowledge games
                      type: object
                  links:
                    properties:
                      self:
                        type: string
                        example: https://api.playable.com/v1/campaigns-types
                    type: object
        '401':
          description: 'Unauthorized.


            Possible reasons:

            Token has expired

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: 'message": "Unauthenticated.'
  /v1/campaign-type/{campaignType}:
    get:
      tags:
      - campaigns
      summary: 'This API responds with a single campaign type resource.


        Requires scope:


        `campaigns.types.view`

        '
      security:
      - clientCredentials:
        - campaigns.types.view
      parameters:
      - name: campaignType
        in: path
        description: campaignType id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Retrieve a single campaign type by id
          content:
            application/json:
              schema:
                properties:
                  data:
                    properties:
                      id:
                        type: integer
                      name:
                        type: string
                        example: Quiz
                      alias:
                        type: string
                        example: quiz
                      variation:
                        type: string
                        example: GAME
                      description:
                        type: string
                      category:
                        type: string
                        example: Knowledge games
                    type: object
                type: object
        '401':
          description: 'Unauthorized.


            Possible reasons:

            Token has expired

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: 'message": "Unauthenticated.'
        '403':
          description: Unable to locate campaign type
  /v1/campaigns:
    get:
      tags:
      - campaigns
      summary: Campaigns list
      description: 'This API lists all campaigns.


        Requires scope:


        `campaigns.list`

        '
      security:
      - clientCredentials:
        - campaigns.list
      parameters:
      - name: sort
        in: query
        description: 'Comma separated list which allows for multi-sorting.

          Available fields are: name, created_on.

          Available options are: asc, desc.

          '
        required: false
        schema:
          type: string
      - name: filter_template
        in: query
        description: Filter for campaign templates.
        required: false
        schema:
          type: string
          enum:
          - 0
          - 1
      - name: filter_name
        in: query
        description: Filter for specific campaign by name.
        required: false
        schema:
          type: string
      - name: filter_type
        in: query
        description: Filter for specific campaign type by alias.
        required: false
        schema:
          type: string
      - name: filter_display
        in: query
        description: Filter for active or inactive campaigns.
        required: false
        schema:
          type: string
          enum:
          - active
          - inactive
      - name: with
        in: query
        required: false
        description: 'Comma separated list of extra fields to include about the campaigns.

          Available options are:

          registrations, sessions, is_instant_win, has_data_wiped, integrations, sections,

          sections.form_fields, bulk_prizes & sections.sessions.

          '
        schema:
          type: array
          items:
            type: string
            example: ''
      - name: page
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: Lists all campaigns available in the system
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
                        timezone:
                          type: string
                          example: Europe/Copenhagen
                          description: 'Available timezones: [link](https://www.php.net/manual/en/timezones.php)'
                        type:
                          type: string
                        active:
                          type: boolean
                        active_from:
                          type: string
                          format: date-time
                        active_to:
                          type: string
                          format: date-time
                        live_url:
                          type: string
                        demo_url:
                          type: string
                        created_on:
                          type: string
                          format: date-time
                        template:
                          properties:
                            enabled:
                              type: boolean
                            image:
                              type: string
                          type: object
                        links:
                          properties:
                            self:
                              type: string
                            integrations:
                              type: string
                            sections:
                              type: string
                            prizes:
                              type: string
                            gameDataStatistics:
                              type: string
                            bulkPrizes:
                              type: string
                          type: object
                      type: object
                  links:
                    items:
                      title: base links
                      properties:
                        first:
                          type: string
                          example: https://api.playable.com/v1/route?page=1
                        last:
                          type: string
                          example: https://api.playable.com/v1/route?page=14
                        prev:
                          type: string
                          example: https://api.playable.com/v1/route?page=13
                        next:
                          type: string
                          example: https://api.playable.com/v1/route?page=2
                      type: object
                  meta:
                    items:
                      title: base meta
                      properties:
                        current_page:
                          type: integer
                        from:
                          type: integer
                        path:
                          type: string
                        per_page:
                          type: integer
                        to:
                          type: integer
                      type: object
        '401':
          description: 'Unauthorized.


            Possible reasons:

            Token has expired

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: 'message": "Unauthenticated.'
  /v1/campaign/{campaign}:
    get:
      tags:
      - campaigns
      summary: Show a single campaign
      description: 'This API responds with a single campaign.


        Requires scope:


        `campaigns.view`

        '
      security:
      - clientCredentials:
        - campaigns.view
      parameters:
      - name: campaign
        in: path
        description: Campaign id
        required: true
        schema:
          type: integer
      - name: with
        in: query
        description: Comma separated list of extra fields to include about the campaigns.
        required: false
        schema:
          type: string
          enum:
          - registrations
          - sessions
          - is_instant_win
          - has_data_wiped
          - integrations
          - sections
          - sections.form_fields
          - bulk_prizes
          - sections.sessions
      responses:
        '200':
          description: Show a single campaign
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    properties:
                      id:
                        type: integer
                      name:
                        type: string
                      timezone:
                        type: string
                        example: Europe/Copenhagen
                        description: 'Available timezones: [link](https://www.php.net/manual/en/timezones.php)'
                      type:
                        type: string
                      active:
                        type: boolean
                      active_from:
                        type: string
                        format: date-time
                      active_to:
                        type: string
                        format: date-time
                      live_url:
                        type: string
                      demo_url:
                        type: string
                      created_on:
                        type: string
                        format: date-time
                      template:
                        properties:
                          enabled:
                            type: boolean
                          image:
                            type: string
                        type: object
                      links:
                        properties:
                          self:
                            type: string
                          integrations:
                            type: string
                          sections:
                            type: string
                          prizes:
                            type: string
                          gameDataStatistics:
                            type: string
                          bulkPrizes:
                            type: string
                        type: object
                    type: object
        '401':
          description: 'Unauthorized.


            Possible reasons:

            Token has expired

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: 'message": "Unauthenticated.'
    post:
      tags:
      - campaigns
      summary: Update Campaign
      description: "This API modifies and responds with an HTTP 204 - No Content. \n\nNotice! minutes & seconds for active_from/to has to be 0.\n\nRequires scope:\n\n`campaigns.modify`\n"
      security:
      - clientCredentials:
        - campaigns.modify
      parameters:
      - name: campaign
        in: path
        description: Campaign id
        required: true
        schema:
          type: integer
      requestBody:
        description: 'name: The new name of the campaign.

          template_enabled: If the campaign should be a template. Either 0 or 1.

          template_image: Absolute path to the campaign template image.

          active_from: When the campaign should be active from. Date format: ISO-8601. Example: 2021-01-01T08:00:00+00:00

          active_to: When the campaign should end. Date format: ISO-8601. Example: 2021-01-01T08:00:00+00:00

          '
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                template_enabled:
                  type: integer
                template_image:
                  type: string
                active_from:
                  type: string
                  format: datetime
                active_to:
                  type: string
                  format: datetime
              required:
              - name
      responses:
        '204':
          description: ''
        '401':
          description: 'Unauthorized.


            Possible reasons:

            Token has expired

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: 'message": "Unauthenticated.'
    delete:
      tags:
      - campaigns
      summary: Delete Campaign
      description: 'This API delete a campaign.


        Requires scope:


        `campaigns.delete`

        '
      security:
      - clientCredentials:
        - campaigns.delete
      parameters:
      - name: campaign
        in: path
        description: Campaign id
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: ''
        '401':
          description: 'Unauthorized.


            Possible reasons:

            Token has expired

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: 'message": "Unauthenticated.'
  /v1/campaign/{campaign}/activate:
    post:
      tags:
      - campaigns
      summary: Activate Campaign
      description: "This API activates and responds with a single campaign resource.\nNotice! active_to cannot be further than the current subscription period & minutes/seconds for active_from/to has to be 0.\n\nRequires scope: \n\n`campaigns.activate`\n"
      security:
      - clientCredentials:
        - campaigns.activate
      parameters:
      - name: campaign
        in: path
        description: Campaign id
        required: true
        schema:
          type: integer
      requestBody:
        description: 'active_from: When the campaign should be active from. Date format: ISO-8601. Example: 2021-01-01T08:00:00+00:00

          active_to: When the campaign should end. Date format: ISO-8601. Example: 2021-01-01T08:00:00+00:00

          '
        content:
          application/json:
            schema:
              type: object
              properties:
                active_from:
                  type: string
                  format: datetime
                active_to:
                  type: string
                  format: datetime
              required:
              - active_from
              - active_to
      responses:
        '204':
          description: ''
        '401':
          description: 'Unauthorized.


            Possible reasons:

            Token has expired

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: 'message": "Unauthenticated.'
  /v1/campaign/{campaign}/pause:
    post:
      tags:
      - campaigns
      summary: Pause Campaign
      description: 'This API pauses a campaign so that it is no longer active.


        This specific API has a rate limit of 1 call every minute.


        Requires scope:


        `campaigns.pause`

        '
      security:
      - clientCredentials:
        - campaigns.pause
      parameters:
      - name: campaign
        in: path
        description: Campaign id
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: ''
        '401':
          description: 'Unauthorized.


            Possible reasons:

            Token has expired

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: 'message": "Unauthenticated.'
  /v1/campaign/{campaign}/resume:
    post:
      tags:
      - campaigns
      summary: Resume campaign
      description: 'This API resumes a paused campaign so that it''s active once more.


        This specific API has a rate limit of 1 call every minute.


        Requires scope:

        `campaigns.resume`

        '
      security:
      - clientCredentials:
        - campaigns.resume
      parameters:
      - name: campaign
        in: path
        description: Campaign id
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: ''
        '401':
          description: 'Unauthorized.


            Possible reasons:

            Token has expired

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: 'message": "Unauthenticated.'
  /v1/campaign/copy/{campaign}:
    post:
      tags:
      - campaigns
      summary: Campaign copy
      description: 'This API copies and responds with the copy of a campaign.


        This specific API has a rate limit of 10 calls every minute.


        Requires scope:


        `campaigns.copy`

        '
      security:
      - clientCredentials:
        - campaigns.copy
      requestBody:
        description: "name: The name of the new campaign\ninclude_bulk_prizes: Should bulk prizes be copied over as well? \nDefault: false. Important: Only unlimited bulk prizes are copied over.\n"
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                include_bulk_prizes:
                  type: boolean
              required:
              - name
              - include_bulk_prizes
      parameters:
      - name: campaign
        in: path
        description: Campaign id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                properties:
                  data:
                    properties:
                      id:
                        type: integer
                      name:
                        type: string
                      timezone:
                        type: string
                        example: Europe/Copenhagen
                        description: 'Available timezones: [link](https://www.php.net/manual/en/timezones.php)'
                      type:
                        type: string
                      active:
                        type: boolean
                      active_from:
                        type: string
                        format: date-time
                      active_to:
                        type: string
                        format: date-time
                      live_url:
                        type: string
                      demo_url:
                        type: string
                      created_on:
                        type: string
                        format: date-time
                      template:
                        properties:
                          enabled:
                            type: boolean
                          image:
                            type: string
                        type: object
                      links:
                        properties:
                          self:
                            type: string
                          integrations:
                            type: string
                          sections:
                            type: string
                          prizes:
                            type: string
                          gameDataStatistics:
                            type: string
                          bulkPrizes:
                            type: string
                        type: object
                    type: object
        '401':
          description: 'Unauthorized.


            Possible reasons:

            Token has expired

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: 'message": "Unauthenticated.'
  /v1/campaign/{campaign}/vouchers:
    get:
      tags:
      - campaigns
      summary: Campaign vouchers
      description: 'List all campaign vouchers.

        This API lists all vouchers associated to the campaign.


        Requires scope:


        `campaigns.voucher.list`

        '
      security:
      - clientCredentials:
        - campaigns.voucher.list
      parameters:
      - name: campaign
        in: path
        description: Campaign id
        required: true
        schema:
          type: integer
      - name: with
        in: query
        description: 'Comma separated list of extra fields to include about the vouchers.

          '
        required: false
        schema:
          type: string
          enum:
          - registration
          - prize
      - name: page
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: Lists all campaign vouchers available in the system
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      properties:
                        id:
                          type: integer
                        seen:
                          type: boolean
                        seen_on:
                          type: string
                          format: datetime
                        used:
                          type: boolean
                        used_on:
                          type: string
                          format: datetime
                        created_on:
                          type: string
                          format: datetime
                      type: object
                  self:
                    type: string
                  links:
                    items:
                      title: base links
                      properties:
                        first:
                          type: string
                          example: https://api.playable.com/v1/route?page=1
                        last:
                          type: string
                          example: https://api.playable.com/v1/route?page=14
                        prev:
                          type: string
                          example: https://api.playable.com/v1/route?page=13
                        next:
                          type: string
                          example: https://api.playable.com/v1/route?page=2
                      type: object
                  meta:
                    items:
                      title: base meta
                      properties:
                        current_page:
                          type: integer
                        from:
                          type: integer
                        path:
                          type: string
                        per_page:
                          type: integer
                        to:
                          type: integer
                      type: object
        '401':
          description: 'Unauthorized.


            Possible reasons:

            Token has expired

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: 'message": "Unauthenticated.'
  /v1/campaign/{campaign}/voucher/{voucher}:
    get:
      tags:
      - campaigns
      summary: Campaign voucher
      description: 'This API return a single campaign voucher.


        Requires scope:


        `campaigns.voucher.view`

        '
      security:
      - clientCredentials:
        - campaigns.voucher.view
      parameters:
      - name: campaign
        in: path
        description: Campaign id
        required: true
        schema:
          type: integer
      - name: voucher
        in: path
        required: true
        schema:
          type: integer
      - name: with
        in: query
        description: 'Comma separated list of extra fields to include about the voucher.

          '
        required: false
        schema:
          type: string
          enum:
          - registration
          - prize
      responses:
        '200':
          description: Lists a single campaign voucher
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    properties:
                      id:
                        type: integer
                      seen:
                        type: boolean
                      seen_on:
                        type: string
                        format: datetime
                      used:
                        type: boolean
                      used_on:
                        type: string
                        format: datetime
                      created_on:
                        type: string
                        format: datetime
                    type: object
        '401':
          description: 'Unauthorized.


            Possible reasons:

            Token has expired

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: 'message": "Unauthenticated.'
  /v1/campaign/voucher:
    delete:
      tags:
      - campaigns
      summary: Delete Campaign vouchers
      description: 'Delete campaign vouchers.

        This API deletes campaign vouchers in the system.


        Requires scope:


        `campaigns.voucher.delete`

        '
      security:
      - clientCredentials:
        - campaigns.voucher.delete
      requestBody:
        description: 'Require an array of integer in query ex. ?vouchers[]=1&vouchers[]=2&vouchers[]=3 or in a body like ex. {"vouchers":[1,2]}

          '
        content:
          application/json:
            schema:
              type: object
              properties:
                vouchers:
                  type: array
                  items:
                    type: integer
                  minItems: 1
                  maxItems: 1000
              required:
              - vouchers
      responses:
        '204':
          description: ''
        '401':
          description: 'Unauthorized.


            Possible reasons:

            Token has expired

            '
 

# --- truncated at 32 KB (96 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/playable/refs/heads/main/openapi/playable-campaigns-api-openapi.yml