Marketo Opportunities API

openapi: 3.2.0
info:
  description: Marketo Engage Rest API
  version: '1.0'
  title: Marketo Engage Rest Opportunities 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: Opportunities
  description: Opportunities Controller
paths:
  /rest/v1/opportunities/schema/fields/{fieldApiName}.json:
    get:
      tags:
      - Opportunities
      summary: Get Opportunity Field by Name
      description: 'Retrieves metadata for single opportunity field. Required Permissions: Read-Write Schema Standard Field, Read-Write Schema Custom Field'
      operationId: getOpportunityFieldByNameUsingGET
      parameters:
      - name: fieldApiName
        in: path
        description: The API name of opportunity field
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfLeadField'
  /rest/v1/opportunities/schema/fields.json:
    get:
      tags:
      - Opportunities
      summary: Get Opportunity Fields
      description: 'Retrieves metadata for all opportunity fields in the target instance. Required Permissions: Read-Write Schema Standard Field, Read-Write Schema Custom Field'
      operationId: getOpportunityFieldsUsingGET
      parameters:
      - 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/ResponseOfLeadField'
  /rest/v1/opportunities.json:
    get:
      tags:
      - Opportunities
      summary: Get Opportunities
      description: 'Returns a list of opportunities based on a filter and set of values. Required Permissions: Read-Only Opportunity, Read-Write Named Opportunity'
      operationId: getOpportunitiesUsingGET
      parameters:
      - name: filterType
        in: query
        description: Opportunities field to filter on
        required: true
        schema:
          type: string
      - name: filterValues
        in: query
        description: Comma-separated list of values to match against
        required: true
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: fields
        in: query
        description: Comma-separated list of fields to include in the response
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: batchSize
        in: query
        description: Maximum number of records to return in the response. Max and default is 300
        required: false
        schema:
          type: integer
          format: int32
      - name: nextPageToken
        in: query
        description: Paging token returned from a previous response
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfCustomObject'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LookupCustomObjectRequest'
        description: customObjectLookupRequest
    post:
      tags:
      - Opportunities
      summary: Sync Opportunities
      description: 'Allows inserting, updating, or upserting of opportunity records into the target instance. Required Permissions: Read-Write Named Opportunity'
      operationId: syncOpportunitiesUsingPOST
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfCustomObject'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SyncCustomObjectRequest'
        description: syncCustomObjectRequest
        required: true
  /rest/v1/opportunities/delete.json:
    post:
      tags:
      - Opportunities
      summary: Delete Opportunities
      description: 'Deletes a list of opportunity records from the target instance. Input records should only have one member, based on the value of ''dedupeBy''. Required Permissions: Read-Write Named Opportunity'
      operationId: deleteOpportunitiesUsingPOST
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfCustomObject'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteCustomObjectRequest'
        description: deleteCustomObjectRequest
  /rest/v1/opportunities/describe.json:
    get:
      tags:
      - Opportunities
      summary: Describe Opportunity
      description: 'Returns object and field metadata for Opportunity type records in the target instance. Required Permissions: Read-Only Opportunity, Read-Write Named Opportunity'
      operationId: describeUsingGET_4
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfObjectMetaData'
  /rest/v1/opportunities/roles.json:
    get:
      tags:
      - Opportunities
      summary: Get Opportunity Roles
      description: 'Returns a list of opportunity roles based on a filter and set of values. Required Permissions: Read-Only Opportunity, Read-Write Named Opportunity'
      operationId: getOpportunityRolesUsingGET
      parameters:
      - name: filterType
        in: query
        description: The role field to filter on. Searchable fields can be retrieved with the Describe Opportunity call.
        required: true
        schema:
          type: string
      - name: filterValues
        in: query
        description: Comma-separated list of field values to return records for
        required: true
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: fields
        in: query
        description: Comma-separated list of fields to include in the response
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: batchSize
        in: query
        description: Maximum number of records to return in the response. Max and default is 300
        required: false
        schema:
          type: integer
          format: int32
      - name: nextPageToken
        in: query
        description: Paging token returned from a previous response
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfCustomObject'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LookupCustomObjectRequest'
        description: Optional JSON request for retrieving opportunity roles with compound keys
    post:
      tags:
      - Opportunities
      summary: Sync Opportunity Roles
      description: 'Allows inserts, updates and upserts of Opportunity Role records in the target instance. Required Permissions: Read-Write Named Opportunity'
      operationId: syncOpportunityRolesUsingPOST
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfCustomObject'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SyncCustomObjectRequest'
        description: syncCustomObjectRequest
        required: true
  /rest/v1/opportunities/roles/delete.json:
    post:
      tags:
      - Opportunities
      summary: Delete Opportunity Roles
      description: 'Deletes a list of opportunities from the target instance. Required Permissions: Read-Write Named Opportunity'
      operationId: deleteOpportunityRolesUsingPOST
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfCustomObject'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteCustomObjectRequest'
        description: deleteCustomObjectRequest
  /rest/v1/opportunities/roles/describe.json:
    get:
      tags:
      - Opportunities
      summary: Describe Opportunity Role
      description: 'Returns object and field metadata for Opportunity Roles in the target instance. Required Permissions: Read-Only Opportunity, Read-Write Named Opportunity'
      operationId: describeOpportunityRoleUsingGET
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfObjectMetaData'
components:
  schemas:
    RelatedObject:
      type: object
      required:
      - field
      - name
      properties:
        field:
          type: string
          description: Name of link field (within link object)
        name:
          type: string
          description: Name of the link object
    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
    ObjectMetaData:
      type: object
      required:
      - createdAt
      - dedupeFields
      - description
      - displayName
      - pluralName
      - fields
      - idField
      - apiName
      - relationships
      - searchableFields
      - updatedAt
      - status
      - version
      properties:
        createdAt:
          type: string
          format: date-time
          description: Datetime when the object type was created
        dedupeFields:
          type: array
          description: List of dedupe fields. Arrays with multiple members are compound keys
          items:
            type: string
        description:
          type: string
          description: Description of the object type
        displayName:
          type: string
          description: UI display-name of the object type
        pluralName:
          type: string
          description: UI plural-name of the custom object type
        fields:
          type: array
          description: List of fields available on the object type
          items:
            $ref: '#/components/schemas/ObjectField'
        idField:
          type: string
          description: Primary id key of the object type
        apiName:
          type: string
          description: Name of the object type
        relationships:
          type: array
          description: List of relationships which the object has
          items:
            $ref: '#/components/schemas/ObjectRelation'
        searchableFields:
          type: array
          description: List of fields valid for use as a filter type in a query
          items:
            type: array
            items:
              type: string
        updatedAt:
          type: string
          format: date-time
          description: Datetime when the object type was most recently updated
        state:
          type: string
          description: Approval state of object type
          enum:
          - draft
          - approved
          - approvedWithDraft
        version:
          type: string
          description: Version of object type that is returned in response
          enum:
          - draft
          - approved
    LeadField:
      type: object
      description: Lead field record
      required:
      - displayName
      - name
      - description
      - dataType
      - isHidden
      - isHtmlEncodingInEmail
      - isSensitive
      - isCustom
      - isApiCreated
      properties:
        displayName:
          type: string
          description: UI display-name of the field
        name:
          type: string
          description: API name of the field
        description:
          type: string
          description: Description of the field
        dataType:
          type: string
          description: Datatype of the field
        length:
          type: integer
          format: int32
          description: Max length of the field. Only applicable to text, string, and text area.
        isHidden:
          type: boolean
          example: false
          description: If set to true, the field is hidden
        isHtmlEncodingInEmail:
          type: boolean
          example: false
          description: If set to true, field is encoded as HTML in email
        isSensitive:
          type: boolean
          example: false
          description: If set to true, field is marked as sensitive
        isCustom:
          type: boolean
          example: false
          description: If set to true, field is custom
        isApiCreated:
          type: boolean
          example: false
          description: If set to true, field was created using REST API
    ResponseOfObjectMetaData:
      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'
        moreResult:
          type: boolean
          example: false
          description: Boolean indicating if there are more results in subsequent pages
        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/ObjectMetaData'
        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'
    DeleteCustomObjectRequest:
      type: object
      required:
      - input
      properties:
        deleteBy:
          type: string
          description: Field to delete records by. Permissible values are idField or dedupeFields as indicated by the result of the corresponding describe record
        input:
          type: array
          description: List of input records
          items:
            $ref: '#/components/schemas/CustomObject'
    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
    CustomObject:
      type: object
      required:
      - marketoGUID
      - seq
      properties:
        marketoGUID:
          type: string
          description: Unique GUID of the custom object records
        reasons:
          type: array
          description: List of reasons why an operation did not succeed. Reasons are only present in API responses and should not be submitted
          items:
            $ref: '#/components/schemas/Reason'
        seq:
          type: integer
          format: int32
          description: Integer indicating the sequence of the record in response. This value is correlated to the order of the records included in the request input. Seq should only be part of responses and should not be submitted.
    ResponseOfLeadField:
      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'
        moreResult:
          type: boolean
          example: false
          description: Boolean indicating if there are more results in subsequent pages
        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/LeadField'
        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'
    SyncCustomObjectRequest:
      type: object
      required:
      - input
      properties:
        action:
          type: string
          description: Type of sync operation to perform
          enum:
          - createOnly
          - updateOnly
          - createOrUpdate
        dedupeBy:
          type: string
          description: Field to deduplicate on. If the value in the field for a given record is not unique, an error will be returned for the individual record.
        input:
          type: array
          description: List of input records
          items:
            $ref: '#/components/schemas/CustomObject'
    ResponseOfCustomObject:
      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'
        moreResult:
          type: boolean
          example: false
          description: Boolean indicating if there are more results in subsequent pages
        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/CustomObject'
        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'
    LookupCustomObjectRequest:
      type: object
      required:
      - input
      properties:
        batchSize:
          type: integer
          format: int32
          description: Maximum number of records to return in the response. Max and default is 300
        fields:
          type: array
          description: 'List of fields to return. If not specified, will return the following fields: marketoGuid, dedupeFields, updatedAt, createdAt, filterType'
          items:
            type: string
        filterType:
          type: string
          description: 'Field to search on. Valid values are: dedupeFields, idFields, and any field defined in searchableFields attribute of Describe endpoint. Default is dedupeFields'
        input:
          type: array
          description: Search values when using a compound key. Each element must include each of the fields in the compound key. Compound keys are determined by the contents of "dedupeFields" in the Describe result for the object
          items:
            $ref: '#/components/schemas/CustomObject'
        nextPageToken:
          type: string
          description: Paging token returned from a previous response
    Reason:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Integer code of the reason
        message:
          type: string
          description: Message describing the reason for the status of the operation
    ObjectField:
      type: object
      properties:
        dataType:
          type: string
          description: Datatype of the field
        displayName:
          type: string
          description: UI display-name of the field
        length:
          type: integer
          format: int32
          description: Max length of the field. Only applicable to text, string, and text area.
        name:
          type: string
          description: Name of the field
        updateable:
          type: boolean
          example: false
          description: Whether the field is updateable
        crmManaged:
          type: boolean
          example: false
          description: Whether the field is managed by CRM (native sync)
    ObjectRelation:
      type: object
      required:
      - field
      - relatedTo
      - type
      properties:
        field:
          type: string
          description: API Name of link field
        relatedTo:
          description: Object to which the field is linked
          $ref: '#/components/schemas/RelatedObject'
        type:
          type: string
          description: Type of the relationship field