Marketo Programs API

openapi: 3.2.0
info:
  description: Marketo Engage Rest API
  version: '1.0'
  title: Marketo Engage Rest Programs 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: Programs
  description: Program Controller
paths:
  /rest/asset/v1/program/byName.json:
    get:
      tags:
      - Programs
      summary: Get Program by Name
      description: 'Retrieves the program record for the given name. Required Permissions: Read-Only Assets, Read-Write Assets'
      operationId: getProgramByNameUsingGET
      parameters:
      - name: name
        in: query
        description: Name of the program
        required: true
        schema:
          type: string
      - name: includeTags
        in: query
        description: Set true to populate program tags
        required: false
        schema:
          type: boolean
      - name: includeCosts
        in: query
        description: Set true to populate program costs
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfProgramResponse'
  /rest/asset/v1/program/byTag.json:
    get:
      tags:
      - Programs
      summary: Get Programs by Tag
      description: 'Retrieves a list of programs matching the tag type and tag values given. Required Permissions: Read-Only Assets, Read-Write Assets'
      operationId: getProgramListByTagUsingGET
      parameters:
      - name: tagType
        in: query
        description: Type of program tag
        required: true
        schema:
          type: string
      - name: tagValue
        in: query
        description: Value of the tag
        required: true
        schema:
          type: string
      - name: maxReturn
        in: query
        description: Maximum number of records to return. Max 200, default 20
        required: false
        schema:
          type: integer
          format: int32
      - name: offset
        in: query
        description: Integer offset for paging
        required: false
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfProgramResponse'
  /rest/asset/v1/program/{id}.json:
    get:
      tags:
      - Programs
      summary: Get Program by Id
      description: 'Retrieves the program record for the given id. Required Permissions: Read-Only Assets, Read-Write Assets'
      operationId: getProgramByIdUsingGET
      parameters:
      - name: id
        in: path
        description: id
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfProgramResponse'
    post:
      tags:
      - Programs
      summary: Update Program Metadata
      description: 'Updates the target program''s metadata. Required Permissions: Read-Write Assets'
      operationId: updateProgramUsingPOST
      parameters:
      - name: id
        in: path
        description: id
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfProgramResponse'
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/UpdateProgramRequest'
        description: updateProgramRequest
        required: true
  /rest/asset/v1/program/{programId}/smartList.json:
    get:
      tags:
      - Programs
      summary: Get Smart List by Program Id
      description: 'Retrieves a Smart List record by its Email Program id. Required Permissions: Read-Asset or Read-Write Asset'
      operationId: getSmartListByProgramIdUsingGET
      parameters:
      - name: programId
        in: path
        description: Id for the email program containing smart list to retrieve
        required: true
        schema:
          type: integer
          format: int64
      - name: includeRules
        in: query
        description: Set true to populate smart list rules. Default false
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfSmartListResponseWithRules'
  /rest/asset/v1/program/{id}/approve.json:
    post:
      tags:
      - Programs
      summary: Approve Program
      description: 'Approves the target program. Only valid for unapproved email programs. Required Permissions: Read-Write Assets'
      operationId: approveProgramUsingPOST
      parameters:
      - name: id
        in: path
        description: id
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfIdResponse'
  /rest/asset/v1/program/{id}/clone.json:
    post:
      tags:
      - Programs
      summary: Clone Program
      description: 'Clones the target program. Required Permissions: Read-Write Assets'
      operationId: cloneProgramUsingPOST
      parameters:
      - name: id
        in: path
        description: id
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfProgramResponse'
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CloneProgramRequest'
        description: cloneProgramRequest
        required: true
  /rest/asset/v1/program/{id}/delete.json:
    post:
      tags:
      - Programs
      summary: Delete Program
      description: 'Deletes the target program. The program may not contain any assets which are in use outside the program. Required Permissions: Read-Write Assets'
      operationId: deleteProgramUsingPOST
      parameters:
      - name: id
        in: path
        description: id
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfIdResponse'
  /rest/asset/v1/program/{id}/unapprove.json:
    post:
      tags:
      - Programs
      summary: Unapprove Program
      description: 'Unapproves the target program. Only valid for approved email programs. Required Permissions: Read-Write Assets'
      operationId: unapproveProgramUsingPOST
      parameters:
      - name: id
        in: path
        description: id
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfIdResponse'
  /rest/asset/v1/programs.json:
    get:
      tags:
      - Programs
      summary: Get Programs
      description: 'Retrieves the list of accessible programs from the target instance. Required Permissions: Read-Only Assets, Read-Write Assets'
      operationId: browseProgramsUsingGET
      parameters:
      - name: maxReturn
        in: query
        description: Maximum number of records to return. Max 200, default 20
        required: false
        schema:
          type: integer
          format: int32
      - name: offset
        in: query
        description: Integer offset for paging
        required: false
        schema:
          type: integer
          format: int32
      - name: filterType
        in: query
        description: Optional filter. Requires filterValues
        required: false
        schema:
          type: string
          enum:
          - id
          - programId
          - folderId
          - workspace
      - name: earliestUpdatedAt
        in: query
        description: Exclude programs prior to this date. Must be valid ISO-8601 string. See <a href="http://developers.marketo.com/rest-api/lead-database/fields/field-types/">Datetime</a> field type description.
        required: false
        schema:
          type: string
      - name: latestUpdatedAt
        in: query
        description: Exclude programs after this date. Must be valid ISO-8601 string. See <a href="http://developers.marketo.com/rest-api/lead-database/fields/field-types/">Datetime</a> field type description.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfBrowseAllPrograms'
    post:
      tags:
      - Programs
      summary: Create Program
      description: 'Creates a new program. Required Permissions: Read-Write Assets'
      operationId: createProgramUsingPOST
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfProgramResponse'
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CreateProgramRequest'
        description: createProgramRequest
        required: true
components:
  schemas:
    CloneProgramRequest:
      type: object
      required:
      - folder
      - name
      properties:
        description:
          type: string
        folder:
          description: JSON representation of parent folder, with members 'id', and 'type' which may be 'Folder' or 'Program'
          $ref: '#/components/schemas/Folder'
        name:
          type: string
          description: Name of the program. Max 255 characters
    ResponseOfBrowseAllPrograms:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
        requestId:
          type: string
        result:
          type: array
          items:
            $ref: '#/components/schemas/BrowseAllPrograms'
        success:
          type: boolean
        warnings:
          type: array
          items:
            type: string
    Tags:
      type: object
      required:
      - tagType
      - tagValue
      properties:
        tagType:
          type: string
          description: Name of the tag
        tagValue:
          type: string
          description: Value of the tag
    CostRequest:
      type: object
      required:
      - cost
      - startDate
      properties:
        cost:
          type: integer
          format: int32
          description: Amount of the cost
        note:
          type: string
          description: Notes on the cost
        startDate:
          type: string
          format: date-time
          description: Start date of the period cost
    CreateProgramRequest:
      type: object
      required:
      - folder
      - name
      - type
      - channel
      properties:
        channel:
          type: string
          description: Channel of the program
        costs:
          type: array
          description: Lists of associated period costs
          items:
            $ref: '#/components/schemas/CostRequest'
        description:
          type: string
        folder:
          description: JSON representation of parent folder, with members 'id', and 'type' which may be 'Folder' or 'Program'
          $ref: '#/components/schemas/Folder'
        name:
          type: string
          description: Name of the program
        tags:
          type: array
          description: List of associated program tags
          items:
            $ref: '#/components/schemas/TagRequest'
        type:
          type: string
          description: Type of the program
    BrowseAllPrograms:
      type: object
      required:
      - channel
      - folder
      - status
      - type
      properties:
        channel:
          type: string
          description: Channel of the program
        createdAt:
          type: string
          format: date-time
          description: Datetime the asset was created
        description:
          type: string
          description: Description of the asset
        folder:
          description: JSON representation of parent folder, with members 'id', and 'type' which may be 'Folder' or 'Program'
          $ref: '#/components/schemas/Folder'
        id:
          type: integer
          format: int64
          description: Id of the asset
        name:
          type: string
          description: Name of the asset
        sfdcId:
          type: string
          description: SFDC id of the program if linked to an SFDC campaign
        sfdcName:
          type: string
          description: Name of the linked SFDC campaign if applicable
        status:
          type: string
          description: Status of the program. Only valid for Email and engagement program types.
          enum:
          - locked
          - unlocked
          - 'on'
          - 'off'
        type:
          type: string
          description: Type of the program
          enum:
          - program
          - event
          - webinar
          - nurture
        updatedAt:
          type: string
          format: date-time
          description: Datetime the asset was most recently updated
        url:
          type: string
          description: Url of the asset in the Marketo UI
        workspace:
          type: string
          description: Name of the workspace
    SmartListFilters:
      type: object
      required:
      - id
      - name
      - ruleTypeId
      - ruleType
      - operator
      - conditions
      description: JSON representation of smart list filters
      properties:
        id:
          type: integer
          format: int32
          description: Id of the filter
        name:
          type: string
          description: Name of filter
        ruleTypeId:
          type: integer
          format: int32
          description: Id of the rule type
        ruleType:
          type: string
          description: Name of rule type
        operator:
          type: string
          description: Name of operator
        conditions:
          type: array
          description: List of smart list conditions
          items:
            $ref: '#/components/schemas/SmartListConditions'
    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
    ProgramResponse:
      type: object
      required:
      - channel
      - costs
      - folder
      - status
      - tags
      - type
      properties:
        channel:
          type: string
          description: Channel of the program
        costs:
          type: array
          description: Lists of associated period costs
          items:
            $ref: '#/components/schemas/Costs'
        createdAt:
          type: string
          format: date-time
          description: Datetime the asset was created
        description:
          type: string
          description: Description of the asset
        endDate:
          type: string
          format: date-time
          description: End date of the program. Applicable to event, email, and webinar type programs
        folder:
          description: JSON representation of parent folder, with members 'id', and 'type' which may be 'Folder' or 'Program'
          $ref: '#/components/schemas/Folder'
        id:
          type: integer
          format: int64
          description: Id of the asset
        name:
          type: string
          description: Name of the asset
        sfdcId:
          type: string
          description: SFDC id of the program if linked to an SFDC campaign
        sfdcName:
          type: string
          description: Name of the linked SFDC campaign if applicable
        startDate:
          type: string
          format: date-time
          description: Start date of program. Applicable to event, email and webinar type programs
        status:
          type: string
          description: Status of the program. Only valid for Email and engagement program types.
          enum:
          - locked
          - unlocked
          - 'on'
          - 'off'
        tags:
          type: array
          description: List of associated program tags
          items:
            $ref: '#/components/schemas/Tags'
        type:
          type: string
          description: Type of the program
          enum:
          - default
          - event
          - webinar
          - nurture
        updatedAt:
          type: string
          format: date-time
          description: Datetime the asset was most recently updated
        url:
          type: string
          description: Url of the asset in the Marketo UI
        workspace:
          type: string
          description: Name of the workspace
    SmartListConditions:
      type: object
      required:
      - activityAttributeId
      - activityAttributeName
      - operator
      - values
      - isPrimary
      description: JSON representation of smart list conditions
      properties:
        activityAttributeId:
          type: integer
          format: int32
          description: Id of the activity attribute
        activityAttributeName:
          type: string
          description: Name of activity attribute
        operator:
          type: string
          description: Value of operator
        values:
          type: array
          description: List of values
          items:
            type: string
        isPrimary:
          type: boolean
          description: Whether the condition is primary or not (first condition of the smart list)
    Folder:
      type: object
      required:
      - id
      - type
      properties:
        id:
          type: integer
          format: int32
          description: Id of the folder
        type:
          type: string
          description: Type of folder
          enum:
          - Folder
          - Program
      description: JSON representation of a folder
    ResponseOfSmartListResponseWithRules:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
        requestId:
          type: string
        result:
          type: array
          items:
            $ref: '#/components/schemas/SmartListResponseWithRules'
        success:
          type: boolean
        warnings:
          type: array
          items:
            type: string
    ResponseOfProgramResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
        requestId:
          type: string
        result:
          type: array
          items:
            $ref: '#/components/schemas/ProgramResponse'
        success:
          type: boolean
        warnings:
          type: array
          items:
            type: string
    Costs:
      type: object
      required:
      - cost
      - startDate
      properties:
        cost:
          type: integer
          format: int32
          description: Amount of the cost
        note:
          type: string
          description: Notes on the cost
        startDate:
          type: string
          format: date-time
          description: Start date of the period cost
    TagRequest:
      type: object
      properties:
        tagType:
          type: string
          description: Type of program tag
        tagValue:
          type: string
          description: Value of the tag
    IdResponse:
      type: object
      required:
      - id
      properties:
        id:
          type: integer
          format: int32
          description: Id of the asset
    ResponseOfIdResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
        requestId:
          type: string
        result:
          type: array
          items:
            $ref: '#/components/schemas/IdResponse'
        success:
          type: boolean
        warnings:
          type: array
          items:
            type: string
    SmartListResponseWithRules:
      type: object
      required:
      - id
      - name
      - description
      - createdAt
      - updatedAt
      - url
      - folder
      - workspace
      properties:
        id:
          type: integer
          format: int64
          description: Id of the smart list
        name:
          type: string
          description: Name of the smart list
        description:
          type: string
          description: Description of the smart list
        createdAt:
          type: string
          format: date-time
          description: Datetime the smart list was created
        updatedAt:
          type: string
          format: date-time
          description: Datetime the smart list was most recently updated
        url:
          type: string
          description: Url of the smart list in the Marketo UI
        folder:
          description: JSON representation of parent folder, with members 'id', and 'type' which may be 'Folder' or 'Program'
          $ref: '#/components/schemas/Folder'
        workspace:
          type: string
          description: Name of the workspace
        rules:
          description: Rules contained in the smart list
          $ref: '#/components/schemas/SmartListRules'
    SmartListRules:
      type: object
      required:
      - filterMatchType
      - triggers
      - filters
      description: JSON representation of smart list rules
      properties:
        filterMatchType:
          type: string
          description: Smart list filter match type (rule logic)
          enum:
          - All
          - Any
          - Advanced
        triggers:
          type: array
          description: List of smart list triggers
          items:
            type: string
        filters:
          type: array
          description: List of smart list filters
          items:
            $ref: '#/components/schemas/SmartListFilters'
    UpdateProgramRequest:
      type: object
      properties:
        costs:
          type: array
          description: Lists of associated period costs that allow you to append, replace, or delete. To append new costs, simply add them to costs array. To replace costs (destructive update), pass new costs and set costsDestructiveUpdate to true. To delete costs, do not pass costs parameter and set costsDestructiveUpdate to true
          items:
            $ref: '#/components/schemas/CostRequest'
        costsDestructiveUpdate:
          type: boolean
          description: Set true to destroy existing costs and replace them with the specified costs
        description:
          type: string
          description: Updated description for the program
        endDate:
          type: string
          description: End date of the program. Applicable to event, email, and webinar type programs
        name:
          type: string
          description: Name of the program
        startDate:
          type: string
          description: Start date of program. Applicable to event, email and webinar type programs
        tags:
          type: array
          description: List of associated program tags
          items:
            $ref: '#/components/schemas/TagRequest'