Listrak List Import API

openapi: 3.2.0
info:
  version: v1
  title: Listrak Email REST List Import API
  description: '# Introduction

    Welcome to the Listrak Email REST API!'
  x-logo:
    url: /Email/Resources/Images/Logo.png
servers:
- url: https://api.listrak.com/email
tags:
- name: List Import
  description: The List Import resource is used to supply an import file in order to import data to a list.
paths:
  /v1/List/{listId}/ListImport:
    get:
      tags:
      - List Import
      summary: Get all List Imports
      description: Retrieves the collection of list imports associated with the specified list.
      operationId: ListImport_GetListImportCollection
      parameters:
      - name: listId
        in: path
        description: Identifier used to locate the list.
        required: true
        schema:
          type: integer
          format: int32
      - name: cursor
        in: query
        description: Value indicating the page of data that's being retrieved. The default value is `Start`.
        required: false
        schema:
          type: string
      - name: count
        in: query
        description: Number of data members to be displayed per page. The default value is `1000` and the maximum value is `5000`.
        required: false
        schema:
          type: string
      - name: startDate
        in: query
        description: Start date that's being used to filter the data members.
        required: false
        schema:
          type: string
      - name: endDate
        in: query
        description: End date that's being used to filter the data members.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection_ListImport'
              example:
                status: 200
                data:
                - importFileId: 0
                  importFileName: null
                  importDate: '0001-01-01T00:00:00'
        '400':
          description: BadRequest
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                status: 400
                error: ERROR_INVALID_PARAMETER
                message: An invalid value was supplied for {Parameter}.
        '404':
          description: NotFound
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                status: 404
                error: ERROR_UNABLE_TO_LOCATE_RESOURCE
                message: Unable to locate a resource associated with the listId supplied.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                status: 401
                error: ERROR_UNAUTHORIZED
                message: Authorization was denied for this request.
      security:
      - OAuth 2:
        - List
        - Contact
      x-code-samples:
      - lang: C#
        source: 'var client = new HttpClient();


          client.BaseAddress = new Uri("https://api.listrak.com/email/");

          client.DefaultRequestHeaders.Add("Authorization", "Bearer " + token);


          var response = await client.GetAsync("v1/List/{listId}/ListImport");

          '
      - lang: PHP
        source: "$client = new \\GuzzleHttp\\Client([\n\t'base_uri' => 'https://api.listrak.com/email/'\n]);\n\n$res = $client->request('GET', 'v1/List/{listId}/ListImport',  [\n\t'headers' => ['Authorization' => 'Bearer ' . $accessToken]\n]);\n"
    post:
      tags:
      - List Import
      summary: Start a List Import
      description: Creates and starts a new import for the specified list. HTTP request body lengths of up to 250 MB are permitted. Because the `fileStream` field must be encoded in Base64, and because the remainder of the JSON payload is counted against the 250 MB limit, the effective maximum import file size is approximately 185 MB (195,000,000 bytes); therefore, only attempt to import files up to 185 MB (195,000,000 bytes) in size.
      operationId: ListImport_PostImportFileResource
      parameters:
      - name: listId
        in: path
        description: Identifier used to locate the list.
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '400':
          description: BadRequest
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                status: 400
                error: ERROR_INVALID_PARAMETER
                message: An invalid value was supplied for {Parameter}.
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceCreated'
              example:
                status: 201
                resourceId: '{ResourceId}'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                status: 401
                error: ERROR_UNAUTHORIZED
                message: Authorization was denied for this request.
        '404':
          description: NotFound
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                status: 404
                error: ERROR_UNABLE_TO_LOCATE_RESOURCE
                message: Unable to locate a resource associated with the listId supplied.
      security:
      - OAuth 2:
        - List
        - Contact
      x-code-samples:
      - lang: C#
        source: "var client = new HttpClient();\n\nclient.BaseAddress = new Uri(\"https://api.listrak.com/email/\");\nclient.DefaultRequestHeaders.Add(\"Authorization\", \"Bearer \" + token);\n\nvar response = await client.PostAsJsonAsync(\"v1/List/{listId}/ListImport\", new\n{\n   FileDelimiter = null,\n   FileMappings = null,\n   FileName = null,\n   FileStream = null,\n   HasColumnNames = false,\n   ImportType = null,\n   SegmentationImportType = null,\n   SuppressEmailNotifications = false,\n   TextQualifier = null,\n   TriggerJourney = false,\n   IncludeUnsubscribed = false\n});\n"
      - lang: PHP
        source: "$client = new \\GuzzleHttp\\Client([\n\t'base_uri' => 'https://api.listrak.com/email/'\n]);\n\n$res = $client->request('POST', 'v1/List/{listId}/ListImport',  [\n\t'headers' => ['Authorization' => 'Bearer ' . $accessToken],\n\t'json' => $jsonBody\n]);\n"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImportFile'
        description: Representation of the import file to utilize.
        required: true
  /v1/List/{listId}/ListImport/{importFileId}:
    get:
      tags:
      - List Import
      summary: Get a List Import
      description: Retrieves the specified list import.
      operationId: ListImport_GetListImportResource
      parameters:
      - name: listId
        in: path
        description: Identifier used to locate the list.
        required: true
        schema:
          type: integer
          format: int32
      - name: importFileId
        in: path
        description: Identifier used to locate the import file.
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Resource_ListImport'
              example:
                status: 200
                data:
                  importFileId: 0
                  importFileName: null
                  importDate: '0001-01-01T00:00:00'
        '400':
          description: BadRequest
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                status: 400
                error: ERROR_INVALID_PARAMETER
                message: An invalid value was supplied for {Parameter}.
        '404':
          description: NotFound
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                status: 404
                error: ERROR_UNABLE_TO_LOCATE_RESOURCE
                message: Unable to locate a resource associated with the listId and importFileId supplied.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                status: 401
                error: ERROR_UNAUTHORIZED
                message: Authorization was denied for this request.
      security:
      - OAuth 2:
        - List
        - Contact
      x-code-samples:
      - lang: C#
        source: 'var client = new HttpClient();


          client.BaseAddress = new Uri("https://api.listrak.com/email/");

          client.DefaultRequestHeaders.Add("Authorization", "Bearer " + token);


          var response = await client.GetAsync("v1/List/{listId}/ListImport/{importFileId}");

          '
      - lang: PHP
        source: "$client = new \\GuzzleHttp\\Client([\n\t'base_uri' => 'https://api.listrak.com/email/'\n]);\n\n$res = $client->request('GET', 'v1/List/{listId}/ListImport/{importFileId}',  [\n\t'headers' => ['Authorization' => 'Bearer ' . $accessToken]\n]);\n"
components:
  schemas:
    Collection_ListImport:
      type: object
      properties:
        status:
          format: int32
          description: HTTP status code.
          type: integer
        data:
          description: Collection of return data from the given call.
          type: array
          items:
            $ref: '#/components/schemas/ListImport'
    ListImport:
      description: A List Import resource.
      type: object
      properties:
        importFileId:
          format: int32
          description: Identifier used to locate the list import.
          type: integer
          readOnly: true
        importFileName:
          description: Filename of an import file.
          type: string
        importDate:
          format: date-time
          description: Date of an import.
          type: string
    ResourceCreated:
      type: object
      properties:
        status:
          format: int32
          description: HTTP status code.
          type: integer
        resourceId:
          description: An identifier used to locate a resource.
          type: string
    ImportFileMapping:
      description: An Import File Mapping resource.
      required:
      - fileColumn
      - fileColumnType
      type: object
      properties:
        segmentationFieldId:
          format: int32
          description: Identifier of the associated profile field.
          type: integer
        defaultValue:
          description: Default value to be used if a value is not provided during the import.
          type: string
        fileColumn:
          format: int32
          description: Number identifying the column's ordinal position in the file, starting from `0`.
          type: integer
        fileColumnType:
          description: Type of value in the column of the import file. Allowed values are `Email`, `SegmentationField`, `Event`, and `ExternalContactID`.
          type: string
    ImportFile:
      description: An Import File resource.
      required:
      - fileDelimiter
      - fileMappings
      - fileName
      - fileStream
      - importType
      - segmentationImportType
      type: object
      properties:
        fileDelimiter:
          description: Delimiter used to separate columns within the file.
          type: string
        fileMappings:
          description: Representation of import file mappings; these map file columns to import fields.
          type: array
          items:
            $ref: '#/components/schemas/ImportFileMapping'
        fileName:
          description: Filename of the import file.
          type: string
        fileStream:
          format: byte
          description: Base64-encoded byte array representation of the import file.
          type: string
        hasColumnNames:
          description: Whether the first line of the import file contains column names.
          type: boolean
        importType:
          description: The type of import to conduct. Allowed values are `AddSubscribers`, `AddSubscribersAndSegmentationData`, `RemoveSubscribers`, and `UpdateSubscribers`.
          type: string
        segmentationImportType:
          description: Strategy to take if imported data already exists. Allowed values are `Update`, `Append`, and `Overwrite`.
          type: string
        suppressEmailNotifications:
          description: Whether to suppress email notifications.
          type: boolean
        textQualifier:
          description: The text qualifier used for the import file.
          type: string
        triggerJourney:
          description: Whether to enter subscribers into all List Subscription journeys associated with this list.
          type: boolean
        includeUnsubscribed:
          description: Whether to update both subscribed and unsubscribed contacts when `ImportType` is `UpdateSubscribers`.
          type: boolean
    Error:
      type: object
      properties:
        status:
          format: int32
          description: HTTP status code.
          type: integer
        error:
          description: Error code indicating what error has occured.
          type: string
        message:
          description: Message describing the status and the error that occurred.
          type: string
    Resource_ListImport:
      type: object
      properties:
        status:
          format: int32
          description: HTTP status code.
          type: integer
        data:
          $ref: '#/components/schemas/ListImport'
          description: Return data.
x-tagGroups:
- name: API Reference
  tags:
  - Campaign
  - Contact
  - ContactSegmentationField
  - Content
  - ContentFolder
  - Conversation
  - ConversationMessage
  - ConversationMessageActivity
  - ConversationMessageLink
  - ConversationMessageLinkClicker
  - ConversationMessageSummary
  - ConversationSummary
  - Event
  - EventGroup
  - Folder
  - IpPool
  - List
  - ListImport
  - ListImportContact
  - ListImportStatus
  - ListImportSummary
  - Message
  - MessageActivity
  - MessageLink
  - MessageLinkClicker
  - MessageStatus
  - MessageSummary
  - SavedAudience
  - SavedMessage
  - SegmentationField
  - SegmentationFieldGroup
  - SplitTest
  - TransactionalMessage
  - TransactionalMessageActivity
  - TransactionalMessageResend