Marketo Companies API

openapi: 3.2.0
info:
  title: Marketo Companies API
  version: '1.0'
  description: 'Operations tagged Companies across 2 of this provider''s published API definitions: marketo-data-ingestion-openapi-original.json, marketo-lead-database-openapi-original.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://mkto-ingestion-api.adobe.io
  description: Marketo Data Ingestion API
- url: https://localhost:8080/
tags:
- name: Companies
  description: Sync company records (createOnly, updateOnly, or createOrUpdate)
paths:
  /subscriptions/{munchkinId}/companies:
    post:
      tags:
      - Companies
      summary: Sync Companies
      description: 'Sync a list of company records. Supports create, update, and upsert operations with deduplication by external company ID or Marketo internal ID. Required permission: `Read-Write Company`.'
      operationId: syncCompanies
      parameters:
      - name: munchkinId
        in: path
        description: Marketo subscription Munchkin ID
        required: true
        schema:
          type: string
          example: 556-RJS-213
      - name: X-Mkto-User-Token
        in: header
        description: Marketo API access token
        required: true
        schema:
          type: string
      - name: X-Correlation-Id
        in: header
        description: Arbitrary string (max 255 characters). Used to trace requests through the system via Marketo Observability Data Stream.
        schema:
          type: string
      - name: X-Request-Source
        in: header
        description: Arbitrary string (max 50 characters). Used to trace the source of requests.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SyncCompaniesRequest'
            example:
              action: createOrUpdate
              dedupeBy: dedupeFields
              input:
              - externalCompanyId: ext-company-001
                company: Acme Corporation
                industry: Technology
                numberOfEmployees: 5000
                annualRevenue: 100000000
              - externalCompanyId: ext-company-002
                company: Globex Industries
                industry: Manufacturing
                numberOfEmployees: 1200
      responses:
        '202':
          description: Accepted – request accepted for async processing
          headers:
            X-Request-Id:
              description: Unique request ID
              schema:
                type: string
        '400':
          description: Bad request – validation error (e.g. invalid dedupeBy, missing company id for updateOnly when dedupeBy is idField, empty input, invalid action)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized – OAuth token is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: https://mkto-ingestion-api.adobe.io
      description: Marketo Data Ingestion API
  /rest/v1/companies.json:
    get:
      tags:
      - Companies
      summary: Get Companies
      description: 'Retrieves company records from the destination instance based on the submitted filter. Required Permissions: Read-Only Company, Read-Write Company'
      operationId: getCompaniesUsingGET
      parameters:
      - name: filterType
        in: query
        description: The company field to filter on. Searchable fields can be retrieved with the Describe Company call.
        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: 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/ResponseOfCompany'
    post:
      tags:
      - Companies
      summary: Sync Companies
      description: 'Allows inserting, updating, or upserting of company records into Marketo. Required Permissions: Read-Write Company'
      operationId: syncCompaniesUsingPOST
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfCompany'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SyncCompanyRequest'
        description: syncCompanyRequest
        required: true
    servers:
    - url: https://localhost:8080/
  /rest/v1/companies/delete.json:
    post:
      tags:
      - Companies
      summary: Delete Companies
      description: 'Deletes the included list of company records from the destination instance. Required Permissions: Read-Write Company'
      operationId: deleteCompaniesUsingPOST
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfCompany'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteCompanyRequest'
        description: deleteCompanyRequest
        required: true
    servers:
    - url: https://localhost:8080/
  /rest/v1/companies/describe.json:
    get:
      tags:
      - Companies
      summary: Describe Companies
      description: 'Returns metadata about companies and the fields available for interaction via the API. Required Permissions: Read-Only Company, Read-Write Company'
      operationId: describeUsingGET
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfObjectMetaData'
    servers:
    - url: https://localhost:8080/
  /rest/v1/companies/schema/fields/{fieldApiName}.json:
    get:
      tags:
      - Companies
      summary: Get Company Field by Name
      description: 'Retrieves metadata for single company field. Required Permissions: Read-Write Schema Standard Field, Read-Write Schema Custom Field'
      operationId: getCompanyFieldByNameUsingGET
      parameters:
      - name: fieldApiName
        in: path
        description: The API name of company field
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfLeadField'
    servers:
    - url: https://localhost:8080/
  /rest/v1/companies/schema/fields.json:
    get:
      tags:
      - Companies
      summary: Get Company Fields
      description: 'Retrieves metadata for all company fields in the target instance. Required Permissions: Read-Write Schema Standard Field, Read-Write Schema Custom Field'
      operationId: getCompanyFieldsUsingGET
      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'
    servers:
    - url: https://localhost:8080/
components:
  schemas:
    Company:
      type: object
      description: Company record. When dedupeBy=dedupeFields, externalCompanyId is required. When dedupeBy=idField, id is required. Additional standard or custom company fields are supported.
      properties:
        id:
          type: integer
          format: int64
          description: Marketo internal company ID. Required when dedupeBy is idField and action is updateOnly.
        externalCompanyId:
          type: string
          description: External company identifier. Required when dedupeBy is dedupeFields.
        company:
          type: string
          description: Company name.
      additionalProperties: true
    ErrorResponse:
      type: object
      description: Error response body returned for non-202 responses.
      properties:
        error_code:
          type: string
          description: Error code.
          example: '4000801'
        message:
          type: string
          description: Error message.
          example: Bad request
    SyncCompaniesRequest:
      required:
      - input
      type: object
      properties:
        action:
          type: string
          description: Sync action. For createOnly and createOrUpdate, only dedupeFields is allowed for dedupeBy. For updateOnly, both dedupeFields and idField are allowed.
          enum:
          - createOnly
          - updateOnly
          - createOrUpdate
          default: createOrUpdate
        dedupeBy:
          type: string
          description: Field to deduplicate on (case-insensitive).
          enum:
          - dedupeFields
          - idField
          default: dedupeFields
        input:
          type: array
          description: List of company attribute name-value pairs.
          items:
            $ref: '#/components/schemas/Company'
    DeleteCompanyRequest:
      type: object
      properties:
        deleteBy:
          type: string
          description: Field to delete company records by. Key may be "dedupeFields" or "idField"
        input:
          type: array
          description: List of company objects. Companies in the list should only contain a member matching the dedupeBy value. Each 'Company' object contains a 'searchableField' for lookup purposes which can be retrieved using the Describe Companies endpoint
          items:
            $ref: '#/components/schemas/Company_2'
    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
    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
    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'
    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
    ResponseOfCompany:
      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/CompanyResponse'
        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'
    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'
    Company_2:
      type: object
      description: Company record. May include any additional 'fields' listed in the Describe Companies endpoint
      properties:
        externalCompanyId:
          type: string
          description: Unique id of the company record
        id:
          type: integer
          description: Unique integer id of the company record
        company:
          type: string
          description: Unique name of the company record
    CompanyResponse:
      type: object
      required:
      - id
      - seq
      properties:
        id:
          type: integer
          format: int64
          description: Unique integer id of the company record
        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.
        status:
          type: string
          description: Status of the operation performed on the record
          enum:
          - created
          - updated
          - deleted
          - skipped
          - added
          - removed
      description: Company record. May include any additional fields listed in the corresponding describe method
    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
    SyncCompanyRequest:
      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. Each 'Company' object contains a 'searchableField' for lookup purposes, and one or more 'fields' to create or update. Both can be retrieved using the Describe Companies endpoint
          items:
            $ref: '#/components/schemas/Company_2'
x-refined-from:
- marketo-data-ingestion-openapi-original.json
- marketo-lead-database-openapi-original.json