openapi: 3.0.3
info:
  title: Lob Exports API
  version: 1.20.2
  description: "Experience direct mail like never before, with unmatched personalization and scalability \x14 all in one intuitive platform."
  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: Exports
paths:
  /uploads/{upl_id}/exports:
    parameters:
    - in: path
      name: upl_id
      description: ID of the upload
      required: true
      schema:
        $ref: '#/components/schemas/upl_id'
    post:
      operationId: upload_export_create
      summary: Create Export
      description: 'Campaign Exports can help you understand exactly which records in a campaign could not be created. By initiating and retrieving an export, you will get row-by-row errors for your campaign. For a step-by-step walkthrough of creating a campaign and exporting failures, see our [Campaigns Guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/campaign-or-triggered-sends/launch-your-first-campaign).


        Create an export file associated with an upload.'
      tags:
      - Exports
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  enum:
                  - all
                  - failures
                  - successes
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/upload_create_export'
        4XX:
          $ref: '#/components/responses/upload_export_error'
      x-codeSamples:
      - lang: Shell
        source: "curl https://api.lob.com/v1/uploads/upl_71be866e430b11e9/exports \\\n  -u <YOUR API KEY>: \\\n  -d \"type=failures\" \\\n"
        label: CURL
      - lang: Python
        source: "with ApiClient(configuration) as api_client:\n  api = UploadsApi(api_client)\n\nexport_model = ExportModel(\n  type = \"all\"\n)\n\ntry:\n  created_export = api.create_export(\"upl_71be866e430b11e9\", export_model)\nexcept ApiException as e:\n  print(e)\n"
        label: PYTHON
      - lang: Ruby
        source: "exportModel = ExportModel.new({\n  type: \"all\"\n})\n\nuploadsApi = UploadsApi.new(config)\n\nbegin\n  createdExport = uploadsApi.create_export(\"upl_71be866e430b11e9\", exportModel)\nrescue => err\n  p err.message\nend\n"
        label: RUBY
  /uploads/{upl_id}/exports/{ex_id}:
    parameters:
    - in: path
      name: upl_id
      description: ID of the upload
      required: true
      schema:
        $ref: '#/components/schemas/upl_id'
    - in: path
      name: ex_id
      description: ID of the export
      required: true
      schema:
        $ref: '#/components/schemas/ex_id'
    get:
      operationId: export_retrieve
      summary: Retrieve Export
      description: Retrieves the details of an existing export. You need only supply the unique export identifier that was returned upon export creation. If you try retrieving an export immediately after creating one (i.e., before we're done processing the export), you will get back an export object with `state = in_progress`.
      tags:
      - Exports
      responses:
        '200':
          description: Returns an export object
          content:
            application/json:
              schema:
                type: object
                required:
                - id
                - dateCreated
                - dateModified
                - deleted
                - s3Url
                - state
                - type
                - uploadId
                properties:
                  id:
                    $ref: '#/components/schemas/ex_id'
                  dateCreated:
                    type: string
                    format: date-time
                    description: A timestamp in ISO 8601 format of the date the export was created
                  dateModified:
                    type: string
                    format: date-time
                    description: A timestamp in ISO 8601 format of the date the export was last modified
                  deleted:
                    type: boolean
                    description: Returns as `true` if the resource has been successfully deleted.
                  s3Url:
                    type: string
                    description: The URL for the generated export file.
                  state:
                    type: string
                    enum:
                    - in_progress
                    - failed
                    - succeeded
                    description: The state of the export file, which can be `in_progress`, `failed` or `succeeded`.
                  type:
                    type: string
                    enum:
                    - all
                    - failures
                    - successes
                    description: The export file type, which can be `all`, `failures` or `successes`.
                  uploadId:
                    $ref: '#/components/schemas/upl_id'
              example:
                id: ex_6a94fe68fd151e0f8
                dateCreated: '2021-07-06T22:51:42.838Z'
                dateModified: '2022-07-06T22:51:42.838Z'
                deleted: false
                s3Url: null
                state: in_progress
                type: failures
                uploadId: upl_71be866e430b11e9
      x-codeSamples:
      - lang: Shell
        source: "curl https://api.lob.com/v1/uploads/upl_71be866e430b11e9/exports/ex_6a94fe68fd151e0f8 \\\n  -u <YOUR API KEY>:\n"
        label: CURL
      - lang: Python
        source: "with ApiClient(configuration) as api_client:\n  api = UploadsApi(api_client)\n\ntry:\n  retrieved_export = api.get_export(\"upl_71be866e430b11e9\", \"ex_6a94fe68fd151e0f8\")\nexcept ApiException as e:\n  print(e)\n"
        label: PYTHON
      - lang: Ruby
        source: "uploadsApi = UploadsApi.new(config)\n\nbegin\n  retrievedExport = uploadsApi.get_export(\"upl_71be866e430b11e9\", \"ex_6a94fe68fd151e0f8\")\nrescue => err\n  p err.message\nend\n"
        label: RUBY
components:
  schemas:
    upload_create_export:
      type: object
      required:
      - message
      - exportId
      properties:
        message:
          title: Message
          enum:
          - Export is processing
          type: string
          default: Export is processing
        exportId:
          title: Export ID
          type: string
          example: ex_2dafd758ed3da9c43
    upl_id:
      type: string
      description: Unique identifier prefixed with `upl_`.
      pattern: ^upl_[a-zA-Z0-9]+$
    ex_id:
      type: string
      description: Unique identifier prefixed with `ex_`.
      pattern: ^ex_[a-zA-Z0-9]+$
  responses:
    upload_export_error:
      description: Create Export Error
      content:
        application/json:
          schema:
            type: object
            required:
            - code
            - message
            - errors
            properties:
              code:
                description: A conventional HTTP status code
                type: number
                enum:
                - 400
                - 404
              message:
                description: A human-readable message with more details about the error
                type: string
              errors:
                description: An array of pre-defined strings that identify an error
                type: array
                items:
                  type: string
            example:
              code: 400
              message: Invalid body, check 'errors' property for more info.
              errors:
              - type must be a string
  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
  - 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