Adobe Suite Mapping sets API

openapi: 3.2.0
info:
  title: Data Prep Mapping sets API
  description: "Data Prep allows data engineers to map, transform, and validate data to and from Experience Data Model (XDM). Use the Data Prep API to programmatically create mapping sets and functions, and transform your data between source and destination schemas.\n- Related documentation:\n  - [Data Prep documentation](https://experienceleague.adobe.com/docs/experience-platform/data-prep/home.html)\n\n- **API paths**:\n  - Platform Gateway URL: https://<spam>platform.adobe.io/\n  - Base path for this API: /data/foundation/conversation\n  - Example of a complete path: https://<span>platform.adobe.io/data/foundation/conversion/languages/el/functions\n\n- **Required headers**:\n    - All calls require the headers `Authorization`, `x-gw-ims-org-id`, and `x-api-key`. For more information on how to obtain these values, see the [authentication tutorial](https://www.adobe.com/go/platform-api-authentication-en).\n    - All resources in Experience Platform are isolated to specific virtual sandboxes. All requests to Platform APIs require the header `x-sandbox-name` whose value is the all-lowercase name of the sandbox the operation will take place in (for example, \"prod\"). See the [sandboxes overview](https://adobe.com/go/sandbox-overview-en) for more information.\n    - All requests with a payload in the request body (such as POST, PUT, and PATCH calls) must include the `Content-Type` header with a value of `application/json`.\n\n- **API error handling**:\n    - Refer to the Experience Platform API troubleshooting guide for [FAQs](https://experienceleague.adobe.com/docs/experience-platform/landing/troubleshooting.html#faq), [API status codes](https://experienceleague.adobe.com/docs/experience-platform/landing/troubleshooting.html#api-status-codes), and [request header errors](https://experienceleague.adobe.com/docs/experience-platform/landing/troubleshooting.html#request-header-errors)."
  version: '1.0'
servers:
- url: //{environment}.adobe.io/data/foundation/conversion
  variables:
    environment:
      default: platform
      enum:
      - platform
      - platform-stage
tags:
- name: Mapping sets
  description: Mapping sets can be used to define how data in a source schema maps to that of a destination schema.
paths:
  /mappingSets:
    get:
      tags:
      - Mapping sets
      summary: List mapping sets
      operationId: listMappingSets
      parameters:
      - name: Authorization
        in: header
        description: The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-api-key
        in: header
        description: The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-gw-ims-org-id
        in: header
        description: The IMS Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-sandbox-name
        in: header
        description: All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the [sandboxes overview](https://adobe.com/go/sandbox-overview-en) for more information.
        required: true
        schema:
          type: string
      - name: limit
        in: query
        description: The total number of records to fetch per page.
        required: true
        allowEmptyValue: false
        schema:
          type: integer
          format: int32
          default: 10
      - name: start
        in: query
        description: Specifies the offset of the pages of results. To get the first page of results, set the value to `start=0`.
        required: true
        allowEmptyValue: false
        schema:
          type: integer
          format: int32
          default: 0
      - name: name
        in: query
        description: Filter the mapping sets by name.
        allowEmptyValue: false
        schema:
          type: string
      - name: orderBy
        in: query
        description: 'Sorts the order of the results. Supported fields are: `createdDate` and `updatedDate`. Prepend the property name with `+` for ascending order and `-` for descending order.'
        allowEmptyValue: false
        schema:
          type: string
          default: lastUpdateDate
      - name: expandSchema
        in: query
        description: Determines whether the full output schema is returned as part of the response.
        schema:
          type: boolean
      responses:
        '200':
          description: A successful response returns a list of all the mapping sets.
          x-summary: List of mapping sets retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MapperSetPage'
        '400':
          description: An invalid request was posted.
          x-summary: Invalid request error
          content: {}
        '401':
          description: The request was unauthorized. Please provide a valid authorization header and try again.
          x-summary: Unauthorized request
          content: {}
        '500':
          description: An internal server error has occurred.
          x-summary: Internal server error
          content: {}
        '503':
          description: The service is unavailable.
          x-summary: Service unavailable
          content: {}
      deprecated: false
    post:
      tags:
      - Mapping sets
      summary: Create a mapping set
      operationId: createMappingSet
      parameters:
      - name: Authorization
        in: header
        description: The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: Content-Type
        in: header
        description: The type of content being sent in the body of the request. This value generally is `application/json`.
        required: true
        schema:
          type: string
      - name: x-api-key
        in: header
        description: The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-gw-ims-org-id
        in: header
        description: The IMS Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-sandbox-name
        in: header
        description: All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the [sandboxes overview](https://adobe.com/go/sandbox-overview-en) for more information.
        required: true
        schema:
          type: string
      requestBody:
        description: The details of the mapping set you want to create.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MappingSet'
        required: true
      responses:
        '200':
          description: A successful response returns information about your newly created mapping set.
          x-summary: Mapping set created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleRepresentation'
              example:
                id: e7c80e4c0d8f4a98a7d400b4e178b635
                version: 0
                createdDate: 1614901254724
                modifiedDate: 1614901254724
                createdBy: '{CREATED_BY}'
                modifiedBy: '{MODIFIED_BY}'
        '400':
          description: An invalid mapping set was requested.
          x-summary: Invalid mapping set request
          content: {}
        '401':
          description: The request was unauthorized. Please provide a valid authorization header and try again.
          x-summary: Unauthorized request
          content: {}
        '500':
          description: An internal server error has occurred.
          x-summary: Internal server error
          content: {}
        '503':
          description: The service is unavailable.
          x-summary: Service unavailable
          content: {}
      deprecated: false
      x-codegen-request-body-name: body
  /mappingSets/validate:
    post:
      tags:
      - Mapping sets
      summary: Validate a mapping set
      operationId: validateMappingSet
      parameters:
      - name: Authorization
        in: header
        description: The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: Content-Type
        in: header
        description: The type of content being sent in the body of the request. This value generally is `application/json`.
        required: true
        schema:
          type: string
      - name: x-api-key
        in: header
        description: The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-gw-ims-org-id
        in: header
        description: The IMS Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-sandbox-name
        in: header
        description: All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the [sandboxes overview](https://adobe.com/go/sandbox-overview-en) for more information.
        required: true
        schema:
          type: string
      requestBody:
        description: The mapping set you want to validate.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MappingSet'
        required: true
      responses:
        '200':
          description: A successful response returns the validation information for the proposed mapping set.
          x-summary: Mapping set validation successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MappingValidationResponse'
              example:
                validationResponse:
                - status: SUCCESS
                  errors: null
                - status: SUCCESS
                  errors: null
                - status: SUCCESS
                  errors: null
        '400':
          description: An invalid mapping set was requested.
          x-summary: Invalid mapping set request
          content: {}
        '401':
          description: The request was unauthorized. Please provide a valid authorization header and try again.
          x-summary: Unauthorized request
          content: {}
        '500':
          description: An internal server error has occurred.
          x-summary: Internal server error
          content: {}
        '503':
          description: The service is unavailable.
          x-summary: Service unavailable
          content: {}
      deprecated: false
      x-codegen-request-body-name: body
  /mappingSets/preview:
    post:
      tags:
      - Mapping sets
      summary: Preview mapping sets
      operationId: previewMappingSet
      parameters:
      - name: Authorization
        in: header
        description: The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: Content-Type
        in: header
        description: The type of content being sent in the body of the request. This value generally is `application/json`.
        required: true
        schema:
          type: string
      - name: x-api-key
        in: header
        description: The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-gw-ims-org-id
        in: header
        description: The IMS Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-sandbox-name
        in: header
        description: All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the [sandboxes overview](https://adobe.com/go/sandbox-overview-en) for more information.
        required: true
        schema:
          type: string
      requestBody:
        description: The data you want to run through as a preview, which will be transformed by the mapping sets within the body.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PreviewRequest'
        required: true
      responses:
        '200':
          description: A successful response returns a preview of your mapped data.
          x-summary: Mapped data preview successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreviewResponse'
        '400':
          description: An invalid request was sent.
          x-summary: Invalid request error
          content: {}
        '401':
          description: The request was unauthorized. Please provide a valid authorization header and try again.
          x-summary: Unauthorized request
          content: {}
        '500':
          description: An internal server error has occurred.
          x-summary: Internal server error
          content: {}
        '503':
          description: The service is unavailable.
          x-summary: Service unavailable
          content: {}
      deprecated: false
      x-codegen-request-body-name: body
  /mappingSets/{MAPPING_SET_ID}:
    get:
      tags:
      - Mapping sets
      summary: Retrieve a mapping set
      operationId: retrieveMappingSet
      parameters:
      - name: MAPPING_SET_ID
        in: path
        description: The ID of the mapping set you are retrieving.
        required: true
        schema:
          type: string
        example: 7c80e4c0d8f4a98a7d400b4e178b635
      - name: Authorization
        in: header
        description: The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-api-key
        in: header
        description: The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-gw-ims-org-id
        in: header
        description: The IMS Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-sandbox-name
        in: header
        description: All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the [sandboxes overview](https://adobe.com/go/sandbox-overview-en) for more information.
        required: true
        schema:
          type: string
      - name: expandSchema
        in: query
        description: Determines whether to return the output schema as part of the response.
        schema:
          type: boolean
          default: false
      - name: version
        in: query
        description: Determines which version of the mapping set to retrieve.
        schema:
          type: integer
          format: int32
          default: 0
      responses:
        '200':
          description: A successful response returns information about the specified mapping set.
          x-summary: Mapping set details retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MappingSet'
        '400':
          description: An invalid request was sent.
          x-summary: Invalid request error
          content: {}
        '401':
          description: The request was unauthorized. Please provide a valid authorization header and try again.
          x-summary: Unauthorized request
          content: {}
        '500':
          description: An internal server error has occurred.
          x-summary: Internal server error
          content: {}
        '503':
          description: The service is unavailable.
          x-summary: Service unavailable
          content: {}
      deprecated: false
    put:
      tags:
      - Mapping sets
      summary: Update a mapping set
      operationId: putMappingSet
      parameters:
      - name: MAPPING_SET_ID
        in: path
        description: The ID of the mapping set you want to update.
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: Content-Type
        in: header
        description: The type of content being sent in the body of the request. This value generally is `application/json`.
        required: true
        schema:
          type: string
      - name: x-api-key
        in: header
        description: The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-gw-ims-org-id
        in: header
        description: The IMS Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-sandbox-name
        in: header
        description: All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the [sandboxes overview](https://adobe.com/go/sandbox-overview-en) for more information.
        required: true
        schema:
          type: string
      requestBody:
        description: The updated content of the mapping set.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MappingSet'
        required: true
      responses:
        '200':
          description: A successful response returns detailed information about your newly updated mapping set.
          x-summary: Mapping set updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MappingSet'
        '400':
          description: An invalid request was sent.
          x-summary: Invalid request error
          content: {}
        '401':
          description: The request was unauthorized. Please provide a valid authorization header and try again.
          x-summary: Unauthorized request
          content: {}
        '500':
          description: An internal server error has occurred.
          x-summary: Internal server error
          content: {}
        '503':
          description: The service is unavailable.
          x-summary: Service unavailable
          content: {}
      deprecated: false
      x-codegen-request-body-name: body
  /mappingSets/{MAPPING_SET_ID}/mappings:
    get:
      tags:
      - Mapping sets
      summary: Retrieve a list of mappings for a specified mapping set
      operationId: listMappings
      parameters:
      - name: MAPPING_SET_ID
        in: path
        description: The ID of the mapping set you are retrieving mappings for.
        required: true
        schema:
          type: string
        example: 7c80e4c0d8f4a98a7d400b4e178b635
      - name: Authorization
        in: header
        description: The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-api-key
        in: header
        description: The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-gw-ims-org-id
        in: header
        description: The IMS Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-sandbox-name
        in: header
        description: All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the [sandboxes overview](https://adobe.com/go/sandbox-overview-en) for more information.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A successful response returns all the mappings for the specified mapping set.
          x-summary: All mappings retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MappingOperation'
        '400':
          description: An invalid request was sent.
          x-summary: Invalid request error
          content: {}
        '401':
          description: The request was unauthorized. Please provide a valid authorization header and try again.
          x-summary: Unauthorized request
          content: {}
        '500':
          description: An internal server error has occurred.
          x-summary: Internal server error
          content: {}
        '503':
          description: The service is unavailable.
          x-summary: Service unavailable
          content: {}
      deprecated: false
  /mappingSets/{MAPPING_SET_ID}/mappings/{MAPPING_ID}:
    get:
      tags:
      - Mapping sets
      summary: Retrieve a mapping from a specified mapping set
      operationId: retrieveMapping
      parameters:
      - name: MAPPING_SET_ID
        in: path
        description: The ID of the mapping set you want to retrieve a specific mapping from.
        required: true
        schema:
          type: string
        example: 7c80e4c0d8f4a98a7d400b4e178b635
      - name: MAPPING_ID
        in: path
        description: The ID of the mapping you want to retrieve.
        required: true
        schema:
          type: string
        example: 394bec970d54410b98e1d4c55a3843ca
      - name: Authorization
        in: header
        description: The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-api-key
        in: header
        description: The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-gw-ims-org-id
        in: header
        description: The IMS Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-sandbox-name
        in: header
        description: All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the [sandboxes overview](https://adobe.com/go/sandbox-overview-en) for more information.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A successful response returns information about the specific mapping.
          x-summary: Specific mapping details retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MappingOperation'
        '400':
          description: An invalid request was sent.
          x-summary: Invalid request error
          content: {}
        '401':
          description: The request was unauthorized. Please provide a valid authorization header and try again.
          x-summary: Unauthorized request
          content: {}
        '500':
          description: An internal server error has occurred.
          x-summary: Internal server error
          content: {}
        '503':
          description: The service is unavailable.
          x-summary: Service unavailable
          content: {}
      deprecated: false
components:
  schemas:
    PreviewRequest:
      title: PreviewRequest
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/JsonNode'
        mappingSet:
          $ref: '#/components/schemas/MappingSet'
      example:
        data:
          id: 1234
          firstName: Jim
          lastName: Seltzer
        mappingSet:
          outputSchema:
            schemaRef:
              id: https://ns.adobe.com/stardust/schemas/89abc189258b1cb1a816d8f2b2341a6d98000ed8f4008305
              contentType: application/vnd.adobe.xed-full+json;version=1
          mappings:
          - sourceType: ATTRIBUTE
            source: id
            destination: _id
            name: id
            description: Identifier field
          - sourceType: ATTRIBUTE
            source: firstName
            destination: person.name.firstName
          - sourceType: ATTRIBUTE
            source: lastName
            destination: person.name.lastName
    SourceType:
      title: SourceType
      type: string
      enum:
      - ATTRIBUTE
      - EXPRESSION
      - STATIC
    SchemaReference:
      title: SchemaReference
      type: object
      properties:
        contentType:
          type: string
        id:
          type: string
    MappingOperation:
      title: MappingOperation
      type: object
      properties:
        createdBy:
          type: string
        createdDate:
          type: string
          format: date-time
        destination:
          type: string
        functionVersion:
          type: integer
          format: int32
        id:
          type: string
        modifiedBy:
          type: string
        modifiedDate:
          type: string
          format: date-time
        source:
          type: string
        sourceType:
          $ref: '#/components/schemas/SourceType'
        expressionAttributes:
          type: array
          items:
            type: string
        version:
          type: integer
          format: int32
        name:
          type: string
        description:
          type: string
      example:
        id: 394bec970d54410b98e1d4c55a3843ca
        version: 0
        createdDate: 1614909614000
        modifiedDate: 1614909614000
        createdBy: '{CREATED_BY}'
        modifiedBy: '{MODIFIED_BY}'
        sourceType: text/x.schema-path
        source: firstName
        destination: person.name.firstName
        identity: false
        primaryIdentity: false
        matchScore: 0.0
        functionVersion: 1
        sourceAttribute: firstName
        destinationXdmPath: person.name.firstName
    TransformErrorInfo:
      title: TransformErrorInfo
      type: object
      properties:
        destination:
          type: string
        exception:
          type: string
        source:
          type: string
        columnName:
          type: string
        sourceType:
          $ref: '#/components/schemas/SourceType'
    MappingSet:
      title: MappingSet
      type: object
      properties:
        allowNullValues:
          type: boolean
        createdBy:
          type: string
        createdDate:
          type: string
          format: date-time
        id:
          type: string
        inputSchema:
          $ref: '#/components/schemas/SchemaRepresentation'
        mappings:
          type: array
          items:
            $ref: '#/components/schemas/MappingOperation'
        modifiedBy:
          type: string
        modifiedDate:
          type: string
          format: date-time
        name:
          type: string
        outputSchema:
          $ref: '#/components/schemas/SchemaRepresentation'
        supportVersion:
          type: string
        version:
          type: integer
          format: int32
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tags'
      example:
        mappings:
        - sourceType: ATTRIBUTE
          source: id
          destination: _id
          name: id
          description: Identifier field
        - sourceType: ATTRIBUTE
          source: firstName
          destination: person.name.firstName
        - sourceType: ATTRIBUTE
      

# --- truncated at 32 KB (38 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/adobe-suite/refs/heads/main/openapi/adobe-suite-mapping-sets-api-openapi.yml