Marketo Bulk Export Leads API

openapi: 3.2.0
info:
  description: Marketo Engage Rest API
  version: '1.0'
  title: Marketo Engage Rest Bulk Export Leads API
  termsOfService: https://www.adobe.com/legal.html
  contact:
    name: Adobe Developer Relations
    url: https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/home
    email: ''
  license:
    name: API License Agreement
    url: https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/api-license
servers:
- url: https://localhost:8080/
tags:
- name: Bulk Export Leads
  description: Bulk Export Leads Controller
paths:
  /bulk/v1/leads/export.json:
    get:
      tags:
      - Bulk Export Leads
      summary: Get Export Lead Jobs
      description: 'Returns a list of export jobs that were created in the past 7 days. Required Permissions: Read-Only Lead'
      operationId: getExportLeadsUsingGET
      parameters:
      - name: status
        in: query
        description: Comma separated list of statuses to filter on.
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
          enum:
          - created
          - queued
          - processing
          - cancelled
          - completed
          - failed
      - name: batchSize
        in: query
        description: The batch size to return. The max and default value is 300.
        required: false
        schema:
          type: integer
          format: int32
      - name: nextPageToken
        in: query
        description: A token will be returned by this endpoint if the result set is greater than the batch size and can be passed in a subsequent call through this parameter. See Paging Tokens for more info.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfExportResponseWithToken'
  /bulk/v1/leads/export/create.json:
    post:
      tags:
      - Bulk Export Leads
      summary: Create Export Lead Job
      description: 'Create export job for search criteria defined via "filter" parameter. Request returns the "exportId" which is passed as a parameter in subsequent calls to Bulk Export Leads endpoints. Use Enqueue Export Lead Job endpoint to queue the export job for processing. Use Get Export Lead Job Status endpoint to retrieve status of export job. Required Permissions: Read-Only Lead'
      operationId: createExportLeadsUsingPOST
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfExportResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExportLeadRequest'
        description: 'exportLeadRequest<br><br>ColumnHeaderNames: A JSON object containing key-value pairs of field and column header names.<br><br>Example:<br><code>"columnHeaderNames":{<br>  "firstName":"First Name",<br>  "lastName":"Last Name",<br>  "email":"Email Address"<br>}</code><br>'
  /bulk/v1/leads/export/{exportId}/cancel.json:
    post:
      tags:
      - Bulk Export Leads
      summary: Cancel Export Lead Job
      description: 'Cancel export job. Required Permissions: Read-Only Lead'
      operationId: cancelExportLeadsUsingPOST
      parameters:
      - name: exportId
        in: path
        description: Id of export batch job.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfExportResponse'
  /bulk/v1/leads/export/{exportId}/enqueue.json:
    post:
      tags:
      - Bulk Export Leads
      summary: Enqueue Export Lead Job
      description: 'Enqueue export job. This will place export job in queue, and will start the job when computing resources become available. The export job must be in "Created" state. Use Get Export Lead Job Status endpoint to retrieve status of export job. Required Permissions: Read-Only Lead'
      operationId: enqueueExportLeadsUsingPOST
      parameters:
      - name: exportId
        in: path
        description: Id of export batch job.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfExportResponse'
  /bulk/v1/leads/export/{exportId}/file.json:
    get:
      tags:
      - Bulk Export Leads
      summary: Get Export Lead File
      description: 'Returns the file content of an export job. The export job must be in "Completed" state. Use Get Export Lead Job Status endpoint to retrieve status of export job. Required Permissions: Read-Only Lead<br><br>The file format is specified by calling the Create Export Lead Job endpoint. The following is an example of the default file format ("CSV").<br><br><code>firstName,lastName,email</code><br><code>Marvin,Gaye,marvin.gaye@motown.com</code>'
      operationId: getExportLeadsFileUsingGET
      parameters:
      - name: exportId
        in: path
        description: Id of export batch job.
        required: true
        schema:
          type: string
      - name: Range
        in: header
        description: To support partial retrieval of extracted data, the HTTP header "Range" of type "bytes" may be specified. See RFC 2616 "Range Retrieval Requests" for more information. If the header is not set, the entire contents will be returned.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObservableOfInputStreamRangeContent'
  /bulk/v1/leads/export/{exportId}/status.json:
    get:
      tags:
      - Bulk Export Leads
      summary: Get Export Lead Job Status
      description: 'Returns status of an export job. Job status is available for 30 days after Completed or Failed status was reached. Required Permissions: Read-Only Lead'
      operationId: getExportLeadsStatusUsingGET
      parameters:
      - name: exportId
        in: path
        description: Id of export batch job.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfExportResponse'
components:
  schemas:
    Error:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Error code of the error. See full list of error codes <a href="https://developers.marketo.com/rest-api/error-codes/">here</a>
        message:
          type: string
          description: Message describing the cause of the error
    ExportLeadRequest:
      type: object
      required:
      - fields
      - filter
      properties:
        columnHeaderNames:
          description: File header field names override (corresponds with REST API name)
          $ref: '#/components/schemas/ColumnHeaderNames'
        fields:
          type: array
          description: Comma-separated list of fields to include in the file
          items:
            type: string
        filter:
          description: 'Lead record selection criteria. Can be one of the following: "createdAt", "updatedAt", "staticListName", "staticListId", "smartListName", "smartListId"'
          $ref: '#/components/schemas/ExportLeadFilter'
        format:
          type: string
          description: File format to create("CSV", "TSV", "SSV"). Default is "CSV"
    ResponseOfExportResponseWithToken:
      type: object
      required:
      - errors
      - requestId
      - result
      - success
      - warnings
      properties:
        errors:
          type: array
          description: Array of errors that occurred if the request was unsuccessful
          items:
            $ref: '#/components/schemas/Error'
        nextPageToken:
          type: string
          description: Paging token given if the result set exceeded the allowed batch size
        requestId:
          type: string
          description: Id of the request made
        result:
          type: array
          description: Array of results for individual records in the operation, may be empty
          items:
            $ref: '#/components/schemas/ExportResponse'
        success:
          type: boolean
          example: false
          description: Whether the request succeeded
        warnings:
          type: array
          description: Array of warnings given for the operation
          items:
            $ref: '#/components/schemas/Warning'
    Warning:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: integer
          format: int32
          description: Integer code of the warning
        message:
          type: string
          description: Message describing the warning
    ExportLeadFilter:
      type: object
      properties:
        createdAt:
          description: Date range to filter new leads on
          $ref: '#/components/schemas/DateRange'
        smartListId:
          type: integer
          format: int32
          description: Id of smart list to retrieve leads from
        smartListName:
          type: string
          description: Name of smart list to retrieve leads from
        staticListId:
          type: integer
          format: int32
          description: Id of static list to retrieve leads from
        staticListName:
          type: string
          description: Name of static list to retrieve leads from
        updatedAt:
          description: Date range to filter updated leads on
          $ref: '#/components/schemas/DateRange'
    ResponseOfExportResponse:
      type: object
      required:
      - errors
      - requestId
      - result
      - success
      - warnings
      properties:
        errors:
          type: array
          description: Array of errors that occurred if the request was unsuccessful
          items:
            $ref: '#/components/schemas/Error'
        requestId:
          type: string
          description: Id of the request made
        result:
          type: array
          description: Array of results for individual records in the operation, may be empty
          items:
            $ref: '#/components/schemas/ExportResponse'
        success:
          type: boolean
          example: false
          description: Whether the request succeeded
        warnings:
          type: array
          description: Array of warnings given for the operation
          items:
            $ref: '#/components/schemas/Warning'
    ObservableOfInputStreamRangeContent:
      type: object
    ColumnHeaderNames:
      type: object
      required:
      - name
      - value
      properties:
        name:
          type: string
          description: REST API name for header field
        value:
          type: string
          description: Value for header field
    DateRange:
      type: object
      properties:
        endAt:
          type: string
          description: End of date range filter (ISO 8601-format)
        startAt:
          type: string
          description: Start of date range filter (ISO-8601 format)
    ExportResponse:
      type: object
      required:
      - exportId
      - status
      properties:
        createdAt:
          type: string
          format: date-time
          description: Date when the export request was created
        errorMsg:
          type: string
          description: Error message in case of "Failed" status
        exportId:
          type: string
          description: Unique id of the export job
        fileSize:
          type: integer
          format: int64
          description: Size of exported file in bytes. This will have a value only when status is "Completed", otherwise null
        fileChecksum:
          type: string
          description: SHA-256 hash of exported file. This will have a value only when status is "Completed", otherwise null
        finishedAt:
          type: string
          format: date-time
          description: Finish time of export job. This will have value only when status is "Completed" or "Failed", otherwise null
        format:
          type: string
          description: Format of file as given in the request ("CSV", "TSV", "SSV")
        numberOfRecords:
          type: integer
          format: int64
          description: Number of records in the export file. This will have value only when status is "Completed", otherwise null
        queuedAt:
          type: string
          format: date-time
          description: Queue time of export job. This will have value when "Queued" status is reached, before that null
        startedAt:
          type: string
          format: date-time
          description: Start time of export job. This will have value when "Processing" status is reached, before that null
        status:
          type: string
          description: Status of the export job ("Created","Queued","Processing","Canceled","Completed","Failed")
      description: Response containing export job status information