openapi: 3.1.0
info:
  title: OwnLocal API — Ads
  version: v1
  description: Print ads converted into digital ad units — create, list, retrieve, update and upload the source
    PDF for an ad.
  contact:
    name: OwnLocal Support
    email: support@ownlocal.com
    url: https://www.ownlocal.com/support/
servers:
- url: https://admin.austin.ownlocal.com
  description: OwnLocal production API host (per the published API reference)
externalDocs:
  description: OwnLocal API Docs
  url: https://api.docs.ownlocal.com/
tags:
- name: Ads
  description: Print ads converted into digital ad units — create, list, retrieve, update and upload the source
    PDF for an ad.
paths:
  /api/v1/ads:
    post:
      tags:
      - Ads
      summary: Creates a new ad
      operationId: createAd
      requestBody:
        required: true
        description: Ad to be created
        content:
          application/json:
            schema:
              type: object
              properties:
                publisherUuid:
                  type: string
                  example: 7e6ffeb2-22f3-4869-b189-d202996814cf
                  format: uuid
                businessUuid:
                  type: string
                  example: 69271d95-e891-4bf7-a9ba-ce249e36e236
                  format: uuid
                adCustomId:
                  type: string
                  example: '234567'
                startDate:
                  type: string
                  example: '2019-08-23'
                  format: date
                endDate:
                  type: string
                  example: '2019-09-23'
                  format: date
              required:
              - publisherUuid
      responses:
        '201':
          description: Ad was successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  adUuid:
                    type: string
                    example: 25c4ae81-095e-4229-a56b-cb2f3ae08f1f
                    format: uuid
                  status:
                    type: string
                    example: Created
                  message:
                    type: string
                    example: Your ad for {publisher name} was successfully created. Provide content for this ad
                      at the url indicated in content_url.
                  content_url:
                    type: string
                    example: https://labs.ownlocal.com/products/datashift/v1/ads/25c4ae81-095e-4229-a56b-cb2f3ae08f1f/content
        '405':
          description: Invalid input
      security:
      - apiKey: []
    get:
      tags:
      - Ads
      summary: Retrieve a list of Ads
      operationId: listAds
      parameters:
      - name: categories
        in: query
        required: false
        schema:
          type: string
        example: foodAndBeverage
      - name: subCategories
        in: query
        required: false
        schema:
          type: string
        example: mexicanFood,restaurants
      - name: offerCountMin
        in: query
        required: false
        schema:
          type: integer
          format: int64
        example: 5
      - name: offerCountMax
        in: query
        required: false
        schema:
          type: integer
          format: int64
        example: 7
      - name: startDateMin
        in: query
        required: false
        schema:
          type: string
          format: date
        example: '2019-09-01T12:34:00'
      - name: startDateMax
        in: query
        required: false
        schema:
          type: string
          format: date
        example: '2019-09-02T16:40:01'
      - name: endDateMin
        in: query
        required: false
        schema:
          type: string
          format: date
        example: '2019-09-29T20:21:00'
      - name: endDateMax
        in: query
        required: false
        schema:
          type: string
          format: date
        example: '2019-09-30T10:56:00'
      - name: dateModifiedMin
        in: query
        required: false
        schema:
          type: string
          format: date
        example: '2019-09-01T10:56:00'
      - name: dateModifiedMax
        in: query
        required: false
        schema:
          type: string
          format: date
        example: '2019-09-07T10:56:00'
      - name: dateCreatedMin
        in: query
        required: false
        schema:
          type: string
          format: date
        example: '2019-09-01T10:56:00'
      - name: dateCreatedMax
        in: query
        required: false
        schema:
          type: string
          format: date
        example: '2019-09-07T12:34:00'
      - name: businessUuids
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
        example:
        - 7f188b7b-7bc8-452e-9bb6-82bb3e13f4b1
        - d69b6855-7e24-47e1-96a0-11c55ca0e9a7
      - name: publisherUuids
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
        example:
        - 7f188b7b-7bc8-452e-9bb6-82bb3e13f4b1
        - d69b6855-7e24-47e1-96a0-11c55ca0e9a7
      - name: sortedBy
        in: query
        required: false
        schema:
          type: string
        example: createdAt,updatedAt,startDate,endDate
      - name: page
        in: query
        required: false
        schema:
          type: integer
          format: int64
        example: 2
      - name: size
        in: query
        required: false
        schema:
          type: integer
          format: int64
        example: 20
      responses:
        '200':
          description: ads found
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ad'
      security:
      - apiKey: []
  /api/v1/ads/{adUuid}:
    get:
      tags:
      - Ads
      summary: Retrieves an ad
      operationId: getAd
      parameters:
      - name: adUuid
        in: path
        description: UUID of the Ad requested
        required: true
        schema:
          type: string
          format: uuid
        example: d17a5879-092e-40e8-acc4-8b04be5b91de
      responses:
        '200':
          description: ad found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ad'
        '404':
          description: Ad {ad_uuid} not found
      security:
      - apiKey: []
    patch:
      tags:
      - Ads
      summary: Updates an ad
      operationId: updateAd
      parameters:
      - name: adUuid
        in: path
        description: UUID of the Ad to update
        required: true
        schema:
          type: string
          format: uuid
        example: d17a5879-092e-40e8-acc4-8b04be5b91de
      requestBody:
        required: true
        description: Ad to be created
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ad'
      responses:
        '200':
          description: ad updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ad'
        '400':
          description: 'Unpermitted params: {invalid params}'
      security:
      - apiKey: []
  /api/v1/ads/{adUuid}/content:
    post:
      tags:
      - Ads
      summary: Upload content for an Ad
      operationId: uploadAdContent
      parameters:
      - name: adUuid
        in: path
        description: UUID of ad to upload content for
        required: true
        schema:
          type: string
          format: uuid
        example: d17a5879-092e-40e8-acc4-8b04be5b91de
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: PDF to be associated with ad
                fileName:
                  type: string
                  description: Name of the file
              required:
              - file
              - fileName
      responses:
        '202':
          description: Content was successfully received
        '400':
          description: Content could not be saved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unacceptableContent'
      security:
      - apiKey: []
components:
  securitySchemes:
    apiKey:
      type: apiKey
      name: Authorization
      in: header
      description: Organization API key sent raw (no scheme prefix) in the Authorization header. Keys are issued
        by OwnLocal support; there is no self-serve key provisioning.
  schemas:
    ad:
      type: object
      properties:
        adUuid:
          type: string
          example: 795d064b-1810-4f6b-bada-6a9f7d534579
          format: uuid
        fileName:
          type: string
          example: '{original_filename}.pdf'
          format: uuid
        adCustomId:
          type: string
          example: '234567'
        businessUuid:
          type: string
          example: 2db5e240-c098-4d59-b3a3-bc7b7abc2c4c
          format: uuid
        publisherUuid:
          type: string
          example: 2db5e240-c098-4d59-b3a3-bc7b7abc2c4c
          format: uuid
        image:
          type: string
          example: https://assets.ownlocal.com/ads/795d064b-1810-4f6b-bada-6a9f7d534579/order_image.jpeg
        startDate:
          type: string
          example: '2019-09-01'
          format: date
        endDate:
          type: string
          example: '2019-09-30'
          format: date
        dateModified:
          type: string
          example: '2019-09-03'
          format: date
        dateCreated:
          type: string
          example: '2019-09-03'
          format: date
        adText:
          type: string
        offerCount:
          type: integer
          example: 4
          format: int64
        offers:
          type: array
          items:
            $ref: '#/components/schemas/offer'
          example:
          - offerUuid: bbfdc747-b2c9-4232-be7a-81dbf5290af4
            offerImage: https://ownlocal.imgix.net/offers/bbfdc747-b2c9-4232-be7a-81dbf5290af4.png
            title: 40% Off Full Interior Detail Package
            description: ''
            originalPrice: ''
            discountPercentage: ''
            discountPrice: ''
            discountOff: ''
            newPrice: ''
            bogo: false
            free: false
            validThrough: ''
            gtin8:
            - class: 77015300
            - class: 77015301
          - offerUuid: 5faaff6a-5ad9-4fcf-b68d-a025b1badd29
            offerImage: https://ownlocal.imgix.net/offers/5faaff6a-5ad9-4fcf-b68d-a025b1badd29.png
            title: Free Brake Inspection with Every Oil Change
            description: ''
            originalPrice: ''
            discountPercentage: ''
            discountPrice: ''
            discountOff: ''
            newPrice: ''
            bogo: false
            free: false
            validThrough: ''
            gtin8:
            - class: 77015300
            - class: 77015301
          - offerUuid: 2df8c96b-f565-4c77-b776-8b02a9a92d30
            offerImage: https://ownlocal.imgix.net/offers/2df8c96b-f565-4c77-b776-8b02a9a92d30.png
            title: 20% Off Full Vehicle Tint
            description: ''
            originalPrice: ''
            discountPercentage: ''
            discountPrice: ''
            discountOff: ''
            newPrice: ''
            bogo: false
            free: false
            validThrough: ''
            gtin8:
            - class: 77011700
            - class: 77011701
          - offerUuid: fea2a6e0-7993-460a-9a54-88acf6dc479b
            offerImage: https://ownlocal.imgix.net/offers/fea2a6e0-7993-460a-9a54-88acf6dc479b.png
            title: $150 Off Windshield Replacement (when going through Insurance)
            description: ''
            originalPrice: ''
            discountPercentage: ''
            discountPrice: ''
            discountOff: ''
            newPrice: ''
            bogo: false
            free: false
            validThrough: ''
            gtin8:
            - class: 77011300
            - class: 77011301
      required:
      - adUuid
      - businessUuid
      - publisherUuid
      - startDate
      - endDate
      - dateModified
      - dateCreated
    offer:
      type: object
      properties:
        offerUuid:
          type: string
          example: bbfdc747-b2c9-4232-be7a-81dbf5290af4
          format: uuid
        offerImage:
          type: string
          example: https://ownlocal.imgix.net/offers/bbfdc747-b2c9-4232-be7a-81dbf5290af4.png
        title:
          type: string
          example: 40% Off Full Interior Detail Package
        description:
          type: string
        originalPrice:
          type: string
        discountPercentage:
          type: string
          example: '40'
        discountPrice:
          type: string
        discountOff:
          type: string
        newPrice:
          type: string
        bogo:
          type: boolean
          example: 'false'
        free:
          type: boolean
          example: 'false'
        validThrough:
          type: string
        gtin8:
          type: array
          items:
            type: object
            properties:
              class:
                type: integer
                format: int64
      required:
      - offerUuid
      - offerImage
      - title
    unacceptableContent:
      type: object
      properties:
        message:
          type: string
          example: A message indicating why the content was unacceptable
security:
- apiKey: []