openapi: 3.0.3
info:
  title: 'Admailr-API API Documentation'
  description: ''
  version: 1.0.0
servers:
  -
    url: 'https://api.admailr.com'
tags:
  -
    name: Banners
    description: ''
  -
    name: 'Campaign categories'
    description: ''
  -
    name: 'Campaign lifecycle'
    description: ''
  -
    name: Campaigns
    description: ''
  -
    name: 'Campaign targeting'
    description: ''
components:
  securitySchemes:
    default:
      type: apiKey
      name: ADMAILR-ADS-API-KEY
      in: header
      description: "    <p>You can pass the same API key in any of these ways:</p>\n    <ul>\n        <li><strong>Header</strong>: <code>ADMAILR-ADS-API-KEY: &lt;your key&gt;</code></li>\n        <li><strong>Bearer token</strong>: <code>Authorization: Bearer &lt;your key&gt;</code></li>\n        <li><strong>Query parameter</strong>: <code>?admailr-ads-api-key=&lt;your key&gt;</code></li>\n    </ul>\n    <p>All examples below default to the custom header for clarity.</p>"
security:
  -
    default: []
paths:
  /api/campaigns/banner-sizes:
    get:
      summary: 'List banner sizes'
      operationId: listBannerSizes
      description: "Returns the creative dimensions that can be used when uploading banners.\nUse the `name` field from this list for the banner `type` payload."
      parameters:
        -
          in: header
          name: ADMAILR-ADS-API-KEY
          description: ''
          example: your-api-key-here
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      name: '300x250 (Medium Rectangle)'
                properties:
                  data:
                    type: array
                    example:
                      -
                        name: '300x250 (Medium Rectangle)'
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          example: '300x250 (Medium Rectangle)'
      tags:
        - Banners
  '/api/campaigns/{campaign_id}/banners':
    get:
      summary: 'List banners for a campaign'
      operationId: listBannersForACampaign
      description: 'Returns the paginated set of creative assets attached to a campaign.'
      parameters:
        -
          in: query
          name: page
          description: 'The page to return.'
          example: 1
          required: false
          schema:
            type: integer
            description: 'The page to return.'
            example: 1
            nullable: false
        -
          in: query
          name: per_page
          description: 'Number of banners per page (defaults to 20).'
          example: 50
          required: false
          schema:
            type: integer
            description: 'Number of banners per page (defaults to 20).'
            example: 50
            nullable: false
        -
          in: header
          name: ADMAILR-ADS-API-KEY
          description: ''
          example: your-api-key-here
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: 42
                      type: 300x250
                      redirect_link: 'https://landing.example.com'
                      status: 1
                  links:
                    first: 'https://api.localhost/api/campaigns/123/banners?page=1'
                    last: 'https://api.localhost/api/campaigns/123/banners?page=5'
                    prev: null
                    next: 'https://api.localhost/api/campaigns/123/banners?page=2'
                  meta:
                    current_page: 1
                    per_page: 20
                    total: 75
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: 42
                        type: 300x250
                        redirect_link: 'https://landing.example.com'
                        status: 1
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 42
                        type:
                          type: string
                          example: 300x250
                        redirect_link:
                          type: string
                          example: 'https://landing.example.com'
                        status:
                          type: integer
                          example: 1
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: 'https://api.localhost/api/campaigns/123/banners?page=1'
                      last:
                        type: string
                        example: 'https://api.localhost/api/campaigns/123/banners?page=5'
                      prev:
                        type: string
                        example: null
                      next:
                        type: string
                        example: 'https://api.localhost/api/campaigns/123/banners?page=2'
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      per_page:
                        type: integer
                        example: 20
                      total:
                        type: integer
                        example: 75
      tags:
        - Banners
    post:
      summary: 'Upload a new banner'
      operationId: uploadANewBanner
      description: 'Creates a creative for the specified campaign. The image must already match one of the allowed banner sizes.'
      parameters:
        -
          in: header
          name: ADMAILR-ADS-API-KEY
          description: ''
          example: your-api-key-here
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: 77
                    type: 300x250
                    redirect_link: 'https://landing.example.com'
                    status: 1
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 77
                      type:
                        type: string
                        example: 300x250
                      redirect_link:
                        type: string
                        example: 'https://landing.example.com'
                      status:
                        type: integer
                        example: 1
      tags:
        - Banners
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                image:
                  type: string
                  format: binary
                  description: 'Banner image file (jpg, png, or gif).'
                  nullable: false
                type:
                  type: string
                  description: 'Banner size name as defined in the platform (eg. "300x250"). Fetch the allowed list via GET /api/campaigns/banner-sizes.'
                  example: '"300x250"'
                  nullable: false
                redirect_link:
                  type: string
                  description: 'HTTPS click-through URL.'
                  example: '"https://landing.example.com"'
                  nullable: false
              required:
                - image
                - type
                - redirect_link
    parameters:
      -
        in: path
        name: campaign_id
        description: 'The ID of the campaign.'
        example: 107
        required: true
        schema:
          type: integer
  '/api/campaigns/{campaign_id}/banners/{id}':
    get:
      summary: 'Show a banner'
      operationId: showABanner
      description: ''
      parameters:
        -
          in: header
          name: ADMAILR-ADS-API-KEY
          description: ''
          example: your-api-key-here
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: 77
                    type: 300x250
                    redirect_link: 'https://landing.example.com'
                    status: 1
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 77
                      type:
                        type: string
                        example: 300x250
                      redirect_link:
                        type: string
                        example: 'https://landing.example.com'
                      status:
                        type: integer
                        example: 1
      tags:
        - Banners
    put:
      summary: 'Update a banner'
      operationId: updateABanner
      description: 'Send a multipart request if you are replacing the image, otherwise JSON is sufficient.'
      parameters:
        -
          in: header
          name: ADMAILR-ADS-API-KEY
          description: ''
          example: your-api-key-here
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: 77
                    type: 728x90
                    redirect_link: 'https://landing.example.com/new'
                    status: 1
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 77
                      type:
                        type: string
                        example: 728x90
                      redirect_link:
                        type: string
                        example: 'https://landing.example.com/new'
                      status:
                        type: integer
                        example: 1
      tags:
        - Banners
      requestBody:
        required: false
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                image:
                  type: string
                  format: binary
                  description: 'The replacement creative (jpg, png, or gif).'
                  nullable: false
                type:
                  type: string
                  description: 'Banner size name (must exist in platform, see GET /api/campaigns/banner-sizes).'
                  example: '"728x90"'
                  nullable: false
                redirect_link:
                  type: string
                  description: 'HTTPS click URL.'
                  example: '"https://landing.example.com/new"'
                  nullable: false
                status:
                  type: integer
                  description: 'Enable/disable flag (1 = active, 0 = disabled).'
                  example: 1
                  nullable: false
    delete:
      summary: 'Delete a banner'
      operationId: deleteABanner
      description: 'Marks the banner as deleted and removes it from the rotation.'
      parameters:
        -
          in: header
          name: ADMAILR-ADS-API-KEY
          description: ''
          example: your-api-key-here
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Banner deleted.'
                properties:
                  message:
                    type: string
                    example: 'Banner deleted.'
      tags:
        - Banners
    parameters:
      -
        in: path
        name: campaign_id
        description: 'The ID of the campaign.'
        example: 107
        required: true
        schema:
          type: integer
      -
        in: path
        name: id
        description: 'The ID of the banner.'
        example: 2115067
        required: true
        schema:
          type: integer
  /api/campaigns/categories:
    get:
      summary: 'List available categories'
      operationId: listAvailableCategories
      description: 'Fetches the latest taxonomy directly from the Admailr Behavior API.'
      parameters:
        -
          in: header
          name: ADMAILR-ADS-API-KEY
          description: ''
          example: your-api-key-here
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      code: 144
                      label: '7-12 Education'
                properties:
                  data:
                    type: array
                    example:
                      -
                        code: 144
                        label: '7-12 Education'
                    items:
                      type: object
                      properties:
                        code:
                          type: integer
                          example: 144
                        label:
                          type: string
                          example: '7-12 Education'
      tags:
        - 'Campaign categories'
  '/api/campaigns/{campaign_id}/cancel':
    patch:
      summary: 'Cancel a campaign'
      operationId: cancelACampaign
      description: ''
      parameters:
        -
          in: header
          name: ADMAILR-ADS-API-KEY
          description: ''
          example: your-api-key-here
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Campaign cancelled.'
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: 'Campaign cancelled.'
      tags:
        - 'Campaign lifecycle'
    parameters:
      -
        in: path
        name: campaign_id
        description: 'The ID of the campaign.'
        example: 107
        required: true
        schema:
          type: integer
  '/api/campaigns/{campaign_id}/start':
    patch:
      summary: 'Start a campaign'
      operationId: startACampaign
      description: "Performs the lightweight preflight checks before activation.\nOnly newly created campaigns in waiting state are accepted."
      parameters:
        -
          in: header
          name: ADMAILR-ADS-API-KEY
          description: ''
          example: your-api-key-here
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Start request accepted.'
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: 'Start request accepted.'
        422:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  success: false
                  message: 'Only newly created campaigns can be started via this endpoint.'
                properties:
                  success:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: 'Only newly created campaigns can be started via this endpoint.'
      tags:
        - 'Campaign lifecycle'
    parameters:
      -
        in: path
        name: campaign_id
        description: 'The ID of the campaign.'
        example: 107
        required: true
        schema:
          type: integer
  '/api/campaigns/{campaign_id}/run':
    patch:
      summary: 'Run a campaign'
      operationId: runACampaign
      description: "Runs the legacy activation checks (budget, spend, approvals) and queues the campaign for delivery.\nOnly paused campaigns are allowed. Running campaigns quickly fail."
      parameters:
        -
          in: header
          name: ADMAILR-ADS-API-KEY
          description: ''
          example: your-api-key-here
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Campaign running.'
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: 'Campaign running.'
        422:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  -
                    description: ''
                    type: object
                    example:
                      success: false
                      message: 'Campaign can only be activated from a paused state.'
                    properties:
                      success:
                        type: boolean
                        example: false
                      message:
                        type: string
                        example: 'Campaign can only be activated from a paused state.'
                  -
                    description: ''
                    type: object
                    example:
                      success: false
                      message: 'Insufficient funds.'
                    properties:
                      success:
                        type: boolean
                        example: false
                      message:
                        type: string
                        example: 'Insufficient funds.'
      tags:
        - 'Campaign lifecycle'
    parameters:
      -
        in: path
        name: campaign_id
        description: 'The ID of the campaign.'
        example: 107
        required: true
        schema:
          type: integer
  '/api/campaigns/{campaign_id}/pause':
    patch:
      summary: 'Pause a campaign'
      operationId: pauseACampaign
      description: ''
      parameters:
        -
          in: header
          name: ADMAILR-ADS-API-KEY
          description: ''
          example: your-api-key-here
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Campaign paused.'
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: 'Campaign paused.'
      tags:
        - 'Campaign lifecycle'
    parameters:
      -
        in: path
        name: campaign_id
        description: 'The ID of the campaign.'
        example: 107
        required: true
        schema:
          type: integer
  /api/campaigns:
    get:
      summary: 'List campaigns'
      operationId: listCampaigns
      description: 'Retrieve a paginated list of campaigns that belong to the authenticated advertiser.'
      parameters:
        -
          in: query
          name: page
          description: 'The page number to return.'
          example: 1
          required: false
          schema:
            type: integer
            description: 'The page number to return.'
            example: 1
            nullable: false
        -
          in: query
          name: per_page
          description: 'Number of items per page (defaults to 20).'
          example: 50
          required: false
          schema:
            type: integer
            description: 'Number of items per page (defaults to 20).'
            example: 50
            nullable: false
        -
          in: header
          name: ADMAILR-ADS-API-KEY
          description: ''
          example: your-api-key-here
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: 17
                      campaign_name: 'Spring Retargeting'
                      status: approved
                      category_ids:
                        - 12
                        - 44
                  links:
                    first: 'https://api.localhost/api/campaigns?page=1'
                    last: 'https://api.localhost/api/campaigns?page=5'
                    prev: null
                    next: 'https://api.localhost/api/campaigns?page=2'
                  meta:
                    current_page: 1
                    per_page: 20
                    total: 100
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: 17
                        campaign_name: 'Spring Retargeting'
                        status: approved
                        category_ids:
                          - 12
                          - 44
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 17
                        campaign_name:
                          type: string
                          example: 'Spring Retargeting'
                        status:
                          type: string
                          example: approved
                        category_ids:
                          type: array
                          example:
                            - 12
                            - 44
                          items:
                            type: integer
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: 'https://api.localhost/api/campaigns?page=1'
                      last:
                        type: string
                        example: 'https://api.localhost/api/campaigns?page=5'
                      prev:
                        type: string
                        example: null
                      next:
                        type: string
                        example: 'https://api.localhost/api/campaigns?page=2'
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      per_page:
                        type: integer
                        example: 20
                      total:
                        type: integer
                        example: 100
      tags:
        - Campaigns
    post:
      summary: 'Create a new campaign'
      operationId: createANewCampaign
      description: ''
      parameters:
        -
          in: header
          name: ADMAILR-ADS-API-KEY
          description: ''
          example: your-api-key-here
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Ad Campaign successfully saved.'
                  campaign: 123
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: 'Ad Campaign successfully saved.'
                  campaign:
                    type: integer
                    example: 123
      tags:
        - Campaigns
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                advertiserName:
                  type: string
                  description: 'The advertiser/company name that will own the campaign.'
                  example: '"Acme Media"'
                  nullable: false
                campaignName:
                  type: string
                  description: 'The public campaign title.'
                  example: '"Q1 Retargeting"'
                  nullable: false
                campaignCategories:
                  type: array
                  description: 'codes of categories to target returned by GET api/campaigns/categories.'
                  example:
                    - 108
                    - 116
                  items:
                    type: string
              required:
                - advertiserName
                - campaignName
                - campaignCategories
  '/api/campaigns/{id}':
    get:
      summary: 'Show campaign details'
      operationId: showCampaignDetails
      description: ''
      parameters:
        -
          in: header
          name: ADMAILR-ADS-API-KEY
          description: ''
          example: your-api-key-here
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: 123
                    campaign_name: 'Q1 Retargeting'
                    status: approved
                    category_ids:
                      - 108
                      - 116
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 123
                      campaign_name:
                        type: string
                        example: 'Q1 Retargeting'
                      status:
                        type: string
                        example: approved
                      category_ids:
                        type: array
                        example:
                          - 108
                          - 116
                        items:
                          type: integer
      tags:
        - Campaigns
    put:
      summary: 'Update a campaign'
      operationId: updateACampaign
      description: ''
      parameters:
        -
          in: header
          name: ADMAILR-ADS-API-KEY
          description: ''
          example: your-api-key-here
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Campaign updated.'
                  campaignData:
                    id: 123
                    status: approved
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: 'Campaign updated.'
                  campaignData:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 123
                      status:
                        type: string
                        example: approved
      tags:
        - Campaigns
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                campaignName:
                  type: string
                  description: 'The new campaign name.'
                  example: '"Holiday Push"'
                  nullable: true
                advertiserName:
                  type: string
                  description: 'The advertiser display name.'
                  example: '"Acme Media"'
                  nullable: true
                dateStart:
                  type: string
                  description: 'ISO or Y-m-d start date. Must be a valid date.'
                  example: '2025-01-01'
                  nullable: true
                dateEnd:
                  type: string
                  description: 'End date (must be after start). Must be a valid date. Must be a date after or equal to <code>dateStart</code>.'
                  example: '2025-02-01'
                  nullable: true
                campaignCategories:
                  type: array
                  description: 'The updated category codes returned by GET api/campaigns/categories.'
                  example:
                    - 108
                    - 116
                  items:
                    type: string
                campaignCountries:
                  type: array
                  description: 'Limit delivery to these country IDs (0 = all, 224 = US).'
                  example:
                    - 0
                  items:
                    type: string
                campaignDevices:
                  type: array
                  description: 'Device codes returned by GET api/campaigns/devices (1 = Mobile Android, 3 = Tablet Android).'
                  example:
                    - 1
                    - 3
                  items:
                    type: string
                campaignDemography:
                  type: array
                  description: 'Array (or JSON string) of demographic rows; every item must include integer keys `gender` (0 = Not Specified, 1 = Male, 2 = Female), `from`, and `to`. Send an empty array or `null` to remove all saved demography rows for this campaign.'
                  example:
                    -
                      gender: 1
                      from: 25
                      to: 34
                  items:
                    type: string
                    nullable: true
                cpc:
                  type: number
                  description: 'Cost-per-click bid in USD (minimum 0.01).'
                  example: 0.45
                  nullable: true
                spendGoal:
                  type: string
                  description: 'Limit type, either "daily" or "weekly".'
                  example: '"daily"'
                  nullable: true
                dailySpend:
                  type: number
                  description: 'Minimum $10 daily spend limit.'
                  example: 150.0
                  nullable: true
                weeklySpend:
                  type: number
                  description: 'Minimum $100 weekly spend limit.'
                  example: 1000.0
                  nullable: true
    parameters:
      -
        in: path
        name: id
        description: 'The ID of the campaign.'
        example: 107
        required: true
        schema:
          type: integer
  /api/campaigns/devices:
    get:
      summary: 'List available devices'
      operationId: listAvailableDevices
      description: 'Returns the device codes and labels supported by the `campaignDevices` payload field.'
      parameters:
        -
          in: header
          name: ADMAILR-ADS-API-KEY
          description: ''
          example: your-api-key-here
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      code: 1
                      label: 'Mobile Android'
                    -
                      code: 3
                      label: 'Tablet Android'
                properties:
                  data:
                    type: array
                    example:
                      -
                        code: 1
                        label: 'Mobile Android'
                      -
                        code: 3
                        label: 'Tablet Android'
                    items:
                      type: object
                      properties:
                        code:
                          type: integer
                          example: 1
                        label:
                          type: string
                          example: 'Mobile Android'
      tags:
        - 'Campaign targeting'
