Lob.com QR Codes API

openapi: 3.0.3
info:
  title: Lob Accounts QR Codes API
  version: 1.22.0
  description: 'The Lob API is organized around REST. Our API is designed to have predictable, resource-oriented URLs and uses HTTP response codes to indicate any API errors. <p>

    '
  license:
    name: MIT
    url: https://mit-license.org/
  contact:
    name: Lob Developer Experience
    url: https://support.lob.com/
    email: lob-openapi@lob.com
  termsOfService: https://www.lob.com/legal
servers:
- url: https://api.lob.com/v1
  description: production
security:
- basicAuth: []
tags:
- name: QR Codes
  description: '

    Lob QR codes allow you to generate a QR code that is unique to each mailpiece, thereby allowing each and every customers to receive a personalized link. See the Create endpoint for <a href="#tag/Letters/operation/letter_create">Letters</a>, <a href="#tag/Postcards/operation/postcard_create">Postcards</a> or <a href="#tag/Self-Mailers/operation/self_mailer_create">Self Mailers</a> to learn how to embed a QR code into your mail piece.


    Webhooks can be used to integrate Lob QR code scans into your omni channel marketing strategy. See the <a href="#tag/Webhooks">Webhooks</a> section of our documentation to learn how to enable the `letter.viewed`, `postcard.viewed` and `self_mailer.viewed` event notifications for your mail pieces.


    Furthermore, our QR code Analytics endpoint can be used to track the impact and engagement rate of your mail sends. Lob can tell you exactly which recipients opened your mailpiece. Our Analytics endpoint allows you to see exactly which recipient scanned a mailpiece, when they scanned it, and more!


    <div class="back-to-top" ><a href="#" onclick="toTopLink()">back to top</a></div>

    '
paths:
  /qr_code_analytics:
    get:
      operationId: qr_codes_list
      summary: List
      description: Returns a list of your QR codes. The QR codes are returned sorted by scan date, with the most recently scanned QR codes appearing first.
      tags:
      - QR Codes
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/include'
      - $ref: '#/components/parameters/date_created'
      - in: query
        name: scanned
        description: Filter list of responses to only include QR codes with at least one scan event.
        schema:
          type: boolean
      - in: query
        name: resource_ids
        description: Filter by the resource ID.
        schema:
          type: array
          maxItems: 100
          default: []
      responses:
        '200':
          description: Returns a list of QR Codes and their analytics.
          content:
            $ref: '#/components/mediaTypes/all_qr_codes'
      x-codeSamples:
      - lang: Shell
        source: 'curl -X GET "https://api.lob.com/v1/qr_code_analytics?limit=2&scanned=true" \

          -u <YOUR API KEY>:

          '
components:
  schemas:
    scans:
      type: object
      properties:
        ip_location:
          type: string
        scan_date:
          type: string
    date_filter:
      type: object
      additionalProperties:
        type: string
      description: 'Filter by ISO-8601 date or datetime, e.g. `{ "gt": "2012-01-01", "lt": "2012-01-31T12:34:56Z" }` where `gt` is >, `lt` is <, `gte` is ≥, and `lte` is ≤.'
    qr_code_scans:
      allOf:
      - type: object
        properties:
          resource_id:
            type: string
            description: Unique identifier for each mail piece.
          date_created:
            $ref: '#/components/schemas/date_created'
          number_of_scans:
            type: number
            description: Number of times the QR Code associated with this mail piece was scanned.
          scans:
            type: array
            description: Detailed scan information associated with each mail piece.
            items:
              $ref: '#/components/schemas/scans'
    count:
      type: integer
      description: number of resources in a set
    object:
      type: string
      description: Value is resource type.
    date_created:
      type: string
      format: date-time
      description: A timestamp in ISO 8601 format of the date the resource was created.
  parameters:
    limit:
      in: query
      name: limit
      required: false
      description: How many results to return.
      schema:
        type: integer
        minimum: 1
        default: 10
        maximum: 100
        example: 10
    include:
      in: query
      name: include
      description: 'Request that the response include the total count by specifying `include=["total_count"]`.

        '
      schema:
        type: array
        items:
          type: string
      explode: true
    date_created:
      in: query
      name: date_created
      description: 'Filter by date created. Accepted formats are ISO-8601 date or datetime, e.g. `{ "gt": "2012-01-01", "lt": "2012-01-31T12:34:56Z" }` where `gt` is >, `lt` is <, `gte` is ≥, and `lte` is ≤.'
      schema:
        $ref: '#/components/schemas/date_filter'
      style: deepObject
      explode: true
    offset:
      in: query
      name: offset
      required: false
      description: An integer that designates the offset at which to begin returning results. Defaults to 0.
      schema:
        type: integer
        default: 0
  mediaTypes:
    all_qr_codes:
      application/json:
        schema:
          allOf:
          - type: object
            properties:
              object:
                $ref: '#/components/schemas/object'
              count:
                $ref: '#/components/schemas/count'
              total_count:
                type: integer
                description: Indicates the total number of records. Provided when the request specifies an "include" query parameter
              scanned_count:
                type: integer
                description: Indicates the number of QR Codes out of `count` that were scanned atleast once.
              data:
                type: array
                description: List of QR code analytics
                items:
                  $ref: '#/components/schemas/qr_code_scans'
        example:
          data:
          - resource_id: ltr_d5a5a89da9106f8
            date_created: '2019-07-27T23:49:01.511Z'
            number_of_scans: 2
            scans:
            - ip_location: 127.0.0.1
              scan_date: '2022-07-27T23:49:01.511Z'
            - ip_location: 127.0.0.1
              scan_date: '2022-07-29T23:45:00.436Z'
          - resource_id: psc_d5a5a89da9106f8
            date_created: '2022-09-27T23:49:01.511Z'
            number_of_scans: 1
            scans:
            - ip_location: 127.0.0.1
              scan_date: '2022-09-27T23:49:01.511Z'
          object: list
          count: 2
          scanned_count: 2
          total_count: 2
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
x-webhooks:
  events:
    post:
      summary: Events
      description: Information about an event
      operationId: event
      tags:
      - Events
      responses:
        '200':
          $ref: '#/components/responses/events'
  tracking_events:
    post:
      summary: Tracking Events
      description: Information about tracking events
      operationId: tracking_event
      tags:
      - Tracking Events
      responses:
        '200':
          $ref: '#/components/responses/tracking_events'
x-tagGroups:
- name: Overview
  tags:
  - Introduction
  - Authentication
  - Getting Started
  - SDKs and Tools
- name: Address Book
  tags:
  - Addresses
  - National Change of Address
- name: Print and Mail API
  tags:
  - Postcards
  - Self Mailers
  - Letters
  - Checks
  - Snap Packs
  - Booklets
  - Bank Accounts
  - Templates
  - Resource Proofs
  - Template Versions
  - Template Design
  - Manage Mail
- name: Campaigns API (BETA)
  tags:
  - Campaigns
  - Creatives
  - Uploads
- name: Informed Delivery Campaign API
  tags:
  - Informed Delivery Campaign
- name: Address Verification API
  tags:
  - US Verifications
  - US Verification Types
  - US Autocompletions
  - Reverse Geocode Lookups
  - Zip Lookups
  - Identity Validation
  - Intl Verifications
- name: Webhooks
  tags:
  - Webhooks
  - Events
  - Tracking Events
- name: Special Features
  tags:
  - Billing Groups
  - Buckslips
  - Buckslip Orders
  - Cards
  - Card Orders
  - QR Codes
  - URL Shortener
- name: Appendix
  tags:
  - Beta Program
  - Errors
  - Rate Limiting
  - Requests and Responses
  - Test and Live Environments
  - Versioning and Changelog