openapi: 3.0.2
info:
  title: Audience Export API
  version: '4.0'
  x-logo:
    url: https://dataservices-docs.segmint.net/images/segmint-logo.png
  description: |-
    The Audience Export API is used to generate file based exports containing UCICs that are in a given audience.
    Exporting these can take a while so the workflow is
    - Generate an export
    - Poll for the status of the export
    - Once completed download the export as a file.
    ### <span style="color:var(--red)">Fields marked with an * are required. </span>
servers:
- url: https://api.segmint.net/v4/audience-export
  description: The production environment
- url: https://api-stage.segmint.net/v4/audience-export
  description: The staging environment
tags:
- name: Generation
  description: Generate an audience export
- name: Status
  description: Get the status of an export
- name: Download
  description: Download a completed audience export
components:
  schemas:
    export_status:
      type: object
      properties:
        export_id:
          type: string
        audience_id:
          type: string
          description: The audience id this export is associated to. NULL if it is
            not associated to one.
        campaign_id:
          type: string
          description: The campaign id this export is associated to. NULL if it is
            not associated to one.
        channel_id:
          type: string
          description: The channel id this export is associated to. NULL if it is
            not associated to one.
        current_job_status:
          type: string
          enum:
          - IN_QUEUE
          - IN_PROCESS
          - DONE
          - ERROR
  parameters:
    partner_id:
      name: partner_id
      in: path
      required: true
      description: The id of the partner you are interacting with
      schema:
        type: string
    campaign_id:
      name: campaign_id
      in: path
      required: true
      description: The id of the campaign you are exporting
      schema:
        type: string
  responses:
    unexpected_error:
      description: An unexpected error occurred. Please try again later. If the problem
        persists please contact us.
    unauthorized:
      description: The request was not authorized. The bearer token may have been
        missing or expired.
    forbidden:
      description: You do not have permission to use this endpoint.
    generationOk:
      description: The export has been queued for generation.
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/export_status"
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      description: Standard bearer authentication. To get a token please see [Authentication](/marketing/api/security).
security:
- Bearer: []
paths:
  "/partners/{partner_id}/audiences/{audience_id}/export":
    get:
      summary: Export an Audience.
      description: |- 
        Start the generation of an export of audience members for an Audience Id. This export does not produce touchpoints to support the influence of goal achievements.
        ### <span style="color:var(--red)">Fields marked with an * are required. </span>
      tags:
      - Generation
      parameters:
      - "$ref": "#/components/parameters/partner_id"
      - name: audience_id
        in: path
        required: true
        description: The id of the audience you are exporting
        schema:
          type: string
      responses:
        '200':
          "$ref": "#/components/responses/generationOk"
        '400':
          description: Failed to queue generation of the export. It may already be
            in queue.
        '401':
          "$ref": "#/components/responses/unauthorized"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          description: The audience does not exist.
        '500':
          "$ref": "#/components/responses/unexpected_error"
  "/partners/{partner_id}/campaigns/{campaign_id}/export":
    get:
      summary: Export a Campaign
      description: |- 
        Start the generation of an export for a Campaign Id. This export does not produce touchpoints to support the influence of goal achievements.
        ### <span style="color:var(--red)">Fields marked with an * are required. </span>
      tags:
      - Generation
      parameters:
      - "$ref": "#/components/parameters/partner_id"
      - "$ref": "#/components/parameters/campaign_id"
      responses:
        '200':
          "$ref": "#/components/responses/generationOk"
        '400':
          description: Failed to queue generation of the export. It may already be
            in queue, or the campaign has no targeting.
        '401':
          "$ref": "#/components/responses/unauthorized"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          description: The campaign does not exist.
        '500':
          "$ref": "#/components/responses/unexpected_error"
  "/partners/{partner_id}/campaigns/{campaign_id}/channels/{channel_id}/export":
    get:
      summary: Export a Campaign on a Channel
      description: |- 
        Start the generation of an export for a Campaign and Channel Id.
        Downloading this list of members will produce touchpoints that can be used to support the influence of goal achievements.
        ### <span style="color:var(--red)">Fields marked with an * are required. </span>
      tags:
      - Generation
      parameters:
      - "$ref": "#/components/parameters/partner_id"
      - "$ref": "#/components/parameters/campaign_id"
      - name: channel_id
        in: path
        required: true
        description: The id of the channel you are exporting
        schema:
          type: string
      responses:
        '200':
          "$ref": "#/components/responses/generationOk"
        '400':
          description: Failed to queue generation of the export. It may already be
            in queue, the campaign has no targeting, the channel is not enabled, or
            the channel is not an exportable channel.
        '401':
          "$ref": "#/components/responses/unauthorized"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          description: The campaign or channel does not exist.
        '500':
          "$ref": "#/components/responses/unexpected_error"
  "/partners/{partner_id}/export/{export_id}/status":
    get:
      summary: Export Status
      description: |- 
        Get the status for one or more export ids.
        ### <span style="color:var(--red)">Fields marked with an * are required. </span>
      tags:
      - Status
      parameters:
      - "$ref": "#/components/parameters/partner_id"
      - name: export_id
        in: path
        required: true
        description: A single export id or a comma delimited list of export ids
        schema:
          type: string
        examples:
          one:
            value: 12345
            summary: A single id
          multiples:
            value: '123,456,789'
            summary: 'Will get status for all 3 ids: 123, 456 and 789'
      responses:
        '200':
          description: Got the status for the requested exports
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/export_status"
        '401':
          "$ref": "#/components/responses/unauthorized"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          description: None of the export ids exist. If a list was provided a 200
            will be the response if at least one of them exists.
        '500':
          "$ref": "#/components/responses/unexpected_error"
  "/partners/{partner_id}/export/{export_id}":
    get:
      summary: Download Export
      description: |- 
        Download a completed export. The status of the export must be `DONE`.
        The response is the contents of a file with a mime type of text/csv.
        ### <span style="color:var(--red)">Fields marked with an * are required. </span>
      tags:
      - Download
      parameters:
      - "$ref": "#/components/parameters/partner_id"
      - name: export_id
        in: path
        required: true
        description: The id of the export to download.
        schema:
          type: string
      responses:
        '200':
          description: A file containing the exported UCICs
          content:
            text/csv:
              schema:
                type: string
        '400':
          description: The export does not have a status of DONE or the export is
            expired.
        '401':
          "$ref": "#/components/responses/unauthorized"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          description: The export id does not exist.
        '500':
          "$ref": "#/components/responses/unexpected_error"
