Adobe Suite Destination configurations API

openapi: 3.2.0
info:
  description: "Adobe Experience Platform Destination SDK (also referred to as the *Destination Authoring API*) is a suite of configuration APIs that allow you to configure destination integration patterns for Experience Platform to deliver audience and profile data to your endpoint, based on data and authentication formats of your choice. \n- **Related documentation**:\n    - [Destination SDK overview](http://www.adobe.com/go/destination-sdk-overview-en)\n    - [Getting started](http://www.adobe.com/go/destination-sdk-getting-started-en)\n\n- **Visualize API calls with Postman (a free, third-party software)**:\n    - [Destination Authoring API Postman collection on GitHub](https://github.com/adobe/experience-platform-postman-samples/blob/master/apis/experience-platform/Destination%20Authoring%20API.postman_collection.json)\n    - [Video guide for creating the Postman environment](https://video.tv.adobe.com/v/28832)\n    - [Steps for importing environments and collections in Postman](https://learning.postman.com/docs/getting-started/importing-and-exporting-data/)\n\n- **API paths**:\n    - PLATFORM Gateway URL: https://<span>platform.adobe.io\n    - Base path for this API: /data/core/activation/authoring\n    - Example of a complete path for making a call to \"/destinations\": https://<span>platform.adobe.io/data/core/activation/authoring/destinations\n\n- **Required headers**:\n    - All service 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](http://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 header `Content-Type` 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?lang=en#faq), [API status codes](https://experienceleague.adobe.com/docs/experience-platform/landing/troubleshooting.html?lang=en#api-status-codes), and [request header errors](https://experienceleague.adobe.com/docs/experience-platform/landing/troubleshooting.html?lang=en#request-header-errors)."
  version: '1.0'
  title: Destination Authoring Destination configurations API
servers:
- url: https://platform.adobe.io/data/core/activation/authoring
  description: Production server
tags:
- name: Destination configurations
  description: Destination configurations contain essential metadata for individual destinations, including their name, category, description, and more. The settings in this configuration also determine how Experience Platform users authenticate to your destination, how it appears in the Experience Platform user interface, and the identities that can be exported to your destination. <br><br> For a description of the functionality supported by this endpoint and an example configuration, see the overview on [destination configurations](http://www.adobe.com/go/destination-sdk-destination-configuration-en) in the Destination SDK documentation.
paths:
  /destinations:
    get:
      tags:
      - Destination configurations
      summary: Retrieve a list of destination configurations
      description: You can retrieve a list of all destination configurations for your IMS Organization by making a GET request to the `/destinations` endpoint.
      operationId: listDestinations
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'
      responses:
        '200':
          description: A successful response returns HTTP status 200 with a list of destination configurations that you have access to, based on the IMS Org ID and sandbox name that you used. One instanceId corresponds to one destination configuration.
          x-summary: Destination configurations retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/destinationResponse'
              examples:
                default:
                  value:
                    items:
                    - instanceId: b0780cb5-2bb7-4409-bf2c-c625ca818588
                      createdDate: '2020-10-28T06:14:09.784471Z'
                      lastModifiedDate: '2021-06-28T06:14:09.784471Z'
                      imsOrg: AC3428435BF324E90A49402A@AdobeOrg
                      sandboxName: prod
                      sandboxId: r5g6660-c5da-11e9-93d4-6d5fc3a66a8e
                      name: Moviestar
                      description: Moviestar is a fictional destination, used for this example.
                      status: TEST
                      customerAuthenticationConfigurations:
                      - authType: BEARER
                      customerDataFields:
                      - name: endpointsInstance
                        type: string
                        title: Select Endpoint
                        description: Moviestar manages several instances across the globe for REST endpoints that our customers are provisioned for. Select your endpoint in the dropdown list.
                        isRequired: true
                        enum:
                        - US
                        - EU
                        - APAC
                        - NZ
                      - name: customerID
                        type: string
                        title: Moviestar Customer ID
                        description: Your customer ID in the Moviestar destination (e.g. abcdef).
                        isRequired: true
                        pattern: ^[A-Za-z]+$
                      uiAttributes:
                        documentationLink: https://www.adobe.com/go/destinations-moviestar-en
                        category: mobile
                        connectionType: Server-to-server
                        frequency: Streaming
                      identityNamespaces:
                        external_id:
                          acceptsAttributes: true
                          acceptsCustomNamespaces: true
                          acceptedGlobalNamespaces:
                            Email: {}
                        another_id:
                          acceptsAttributes: true
                          acceptsCustomNamespaces: true
                      segmentMappingConfig:
                        mapExperiencePlatformSegmentName: false
                        mapExperiencePlatformSegmentId: false
                        mapUserInput: false
                        audienceTemplateId: cbf90a70-96b4-437b-86be-522fbdaabe9c
                      schemaConfig:
                        profileFields:
                        - name: a_custom_attribute
                          title: a_custom_attribute
                          description: This is a fixed attribute on your destination side that customers can map profile attributes to. For example, the phoneNumber value in Experience Platform could be phoneNo on your side.
                          type: string
                          isRequired: false
                          readOnly: false
                          hidden: false
                        profileRequired: true
                        segmentRequired: true
                        identityRequired: true
                      aggregation:
                        aggregationType: BEST_EFFORT
                        bestEffortAggregation:
                          maxUsersPerRequest: 10
                          splitUserById: false
                      destinationDelivery:
                      - authenticationRule: CUSTOMER_AUTHENTICATION
                        destinationServerId: 9c77000a-4559-40ae-9119-a04324a3ecd4
                      destConfigId: 410631b8-f6b3-4b7c-82da-7998aa3f327c
                      backfillHistoricalProfileData: true
        '401':
          description: Unauthorized. A mandatory header might be missing from the request or you may be missing permissions to access the resource. Verify your request and try again.
          x-summary: Unauthorized access
        '403':
          description: Forbidden. The requester is not authorized to access the resource or a mandatory header might be missing from the request. Verify your request and try again.
          x-summary: Access forbidden
    post:
      tags:
      - Destination configurations
      summary: Create a destination configuration
      description: You can create a new destination configuration by making a POST request to the `/destinations` endpoint. <br><br> The payload below includes all parameters for file-based destinations accepted by the `/authoring/destinations` endpoint. Note that you do not have to add all parameters to your API call, and that the payload is customizable, according to your API requirements.
      operationId: createDestination
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'
      requestBody:
        description: Destination configuration object for a new destination. The request creates an Amazon S3 destination configuration, configured by the parameters provided in the payload. The payload below includes all parameters for file-based destinations accepted by the `/authoring/destinations` endpoint. Note that you do not have to add all parameters to your API call, and that the payload is customizable, according to your API requirements. <br><br> Refer to the Destination SDK documentation for an example of a destination configuration for a [file-based](https://experienceleague.adobe.com/en/docs/experience-platform/destinations/destination-sdk/guides/configure-file-based-destination-instructions#create-destination-configuration) and a [streaming destination](https://experienceleague.adobe.com/en/docs/experience-platform/destinations/destination-sdk/guides/configure-destination-instructions#create-destination-configuration).
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/destination'
      responses:
        '200':
          description: A successful response returns HTTP status 200 with details of your newly created destination configuration.
          x-summary: Destination configuration created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/destinationResponse'
        '400':
          description: Bad request. The request payload was incorrectly formatted. Check your payload formatting before trying again.
          x-summary: Bad request due to incorrect payload format
        '401':
          description: Unauthorized. A mandatory header might be missing from the request or you may be missing permissions to access the resource. Verify your request and try again.
          x-summary: Unauthorized access
        '403':
          description: Forbidden. The requester is not authorized to access the resource or a mandatory header might be missing from the request. Verify your request before trying again.
          x-summary: Access forbidden
  /destinations/{INSTANCE_ID}:
    get:
      tags:
      - Destination configurations
      summary: Retrieve a destination configuration
      description: You can retrieve detailed information about a specific destination configuration by making a GET request to the `/destinations` endpoint and providing the ID of the destination configuration you want to retrieve.
      operationId: retrieveDestination
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'
      - name: INSTANCE_ID
        in: path
        description: The ID of the destination configuration that you want to retrieve.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A successful response returns HTTP status 200 with the details of the destination configuration corresponding to the INSTANCE_ID provided in the call.
          x-summary: Destination configuration retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/destinationResponse'
              examples:
                default:
                  value:
                    items:
                    - instanceId: b0780cb5-2bb7-4409-bf2c-c625ca818588
                      createdDate: '2020-10-28T06:14:09.784471Z'
                      lastModifiedDate: '2021-06-28T06:14:09.784471Z'
                      imsOrg: AC3428435BF324E90A49402A@AdobeOrg
                      sandboxName: prod
                      sandboxId: r5g6660-c5da-11e9-93d4-6d5fc3a66a8e
                      name: Moviestar
                      description: Moviestar is a fictional destination, used for this example.
                      status: TEST
                      customerAuthenticationConfigurations:
                      - authType: BEARER
                      customerDataFields:
                      - name: endpointsInstance
                        type: string
                        title: Select Endpoint
                        description: Moviestar manages several instances across the globe for REST endpoints that our customers are provisioned for. Select your endpoint in the dropdown list.
                        isRequired: true
                        enum:
                        - US
                        - EU
                        - APAC
                        - NZ
                      - name: customerID
                        type: string
                        title: Moviestar Customer ID
                        description: Your customer ID in the Moviestar destination (e.g. abcdef).
                        isRequired: true
                        pattern: ^[A-Za-z]+$
                      uiAttributes:
                        documentationLink: https://www.adobe.com/go/destinations-moviestar-en
                        category: mobile
                        connectionType: Server-to-server
                        frequency: Streaming
                      identityNamespaces:
                        external_id:
                          acceptsAttributes: true
                          acceptsCustomNamespaces: true
                          acceptedGlobalNamespaces:
                            Email: {}
                        another_id:
                          acceptsAttributes: true
                          acceptsCustomNamespaces: true
                      segmentMappingConfig:
                        mapExperiencePlatformSegmentName: false
                        mapExperiencePlatformSegmentId: false
                        mapUserInput: false
                        audienceTemplateId: cbf90a70-96b4-437b-86be-522fbdaabe9c
                      schemaConfig:
                        profileFields:
                        - name: a_custom_attribute
                          title: a_custom_attribute
                          description: This is a fixed attribute on your destination side that customers can map profile attributes to. For example, the phoneNumber value in Experience Platform could be phoneNo on your side.
                          type: string
                          isRequired: false
                          readOnly: false
                          hidden: false
                        profileRequired: true
                        segmentRequired: true
                        identityRequired: true
                      aggregation:
                        aggregationType: BEST_EFFORT
                        bestEffortAggregation:
                          maxUsersPerRequest: 10
                          splitUserById: false
                      destinationDelivery:
                      - authenticationRule: CUSTOMER_AUTHENTICATION
                        destinationServerId: 9c77000a-4559-40ae-9119-a04324a3ecd4
                      destConfigId: 410631b8-f6b3-4b7c-82da-7998aa3f327c
                      backfillHistoricalProfileData: true
        '400':
          description: Bad request. The request payload was incorrectly formatted. Check your payload formatting before trying again.
          x-summary: Bad request due to formatting error
        '401':
          description: Unauthorized. A mandatory header might be missing from the request or you may be missing permissions to access the resource. Verify your request before trying again.
          x-summary: Unauthorized access
        '403':
          description: Forbidden. The requester is not authorized to access the resource or a mandatory header might be missing from the request. Verify your request before trying again.
          x-summary: Access forbidden
        '404':
          description: Resource not found. Verify that you are using the correct destination configuration ID before trying again.
          x-summary: Resource not found
    put:
      tags:
      - Destination configurations
      summary: Update a destination configuration
      description: You can update an existing destination configuration by making a PUT request to the `/destinations` endpoint with the updated payload. <br><br> To obtain an existing destination configuration and its corresponding `{INSTANCE_ID}`, see [Retrieve a destination configuration](#operation/retrieveDestination).
      operationId: updateDestination
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'
      - name: INSTANCE_ID
        in: path
        description: The ID of the destination configuration that you want to update. To obtain an existing destination configuration and its corresponding `{INSTANCE_ID}`, see [Retrieve a destination configuration](#operation/retrieveDestination).
        required: true
        schema:
          type: string
      requestBody:
        description: Destination configuration object to update existing destination. The request updates the destination configuration with the parameters provided in the payload. See an example of a destination configuration for a [file-based](https://experienceleague.adobe.com/en/docs/experience-platform/destinations/destination-sdk/guides/configure-file-based-destination-instructions#create-destination-configuration) and a [streaming destination](https://experienceleague.adobe.com/en/docs/experience-platform/destinations/destination-sdk/guides/configure-destination-instructions#create-destination-configuration).
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/destination'
      responses:
        '200':
          description: A successful response returns HTTP status 200 with the details of your updated destination configuration.
          x-summary: Destination configuration updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/destinationResponse'
        '400':
          description: Bad request. The request payload was incorrectly formatted. Check your payload formatting before trying again.
          x-summary: Bad request due to incorrect formatting
        '401':
          description: Unauthorized. A mandatory header might be missing from the request or you may be missing permissions to access the resource. Verify your request and try again.
          x-summary: Unauthorized access
        '403':
          description: Forbidden. The requester is not authorized to access the resource or a mandatory header might be missing from the request. Verify your request before trying again.
          x-summary: Access forbidden
        '404':
          description: Resource not found. Verify that you are using the correct destination configuration ID before trying again.
          x-summary: Resource not found
    delete:
      tags:
      - Destination configurations
      summary: Delete a destination configuration
      description: You can delete an existing destination configuration by making a DELETE request to the `/destinations` endpoint with the `{INSTANCE_ID}` of the destination configuration that you want to delete. <br><br> To obtain an existing destination configuration and its corresponding `{INSTANCE_ID}`, see [Retrieve a destination configuration](#operation/retrieveDestination).
      operationId: deleteDestination
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'
      - name: INSTANCE_ID
        in: path
        description: The ID of the destination configuration you want to delete.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A successful response returns HTTP status 200 along with an empty HTTP response.
          x-summary: Resource deleted successfully
        '401':
          description: Unauthorized. A mandatory header might be missing from the request or you may be missing permissions to access the resource. Verify your request and try again.
          x-summary: Unauthorized access
        '403':
          description: Forbidden. The requester is not authorized to access the resource or a mandatory header might be missing from the request. Verify your request before trying again.
          x-summary: Access forbidden
        '404':
          description: Resource not found. Verify that you are using the correct destination configuration ID before trying again.
          x-summary: Resource not found
components:
  schemas:
    destinationResponse:
      allOf:
      - $ref: '#/components/schemas/response'
      - $ref: '#/components/schemas/destination'
    customerDataField:
      type: object
      properties:
        name:
          type: string
          example: endpointsInstance
          description: Provide a name for the custom field you are introducing.
        type:
          type: string
          example: string
          description: Indicates what type of custom field you are introducing. Accepted values are string, object, integer.
          enum:
          - string
          - object
          - integer
        title:
          type: string
          example: Select endpoint
          description: Indicates the name of the field, as it is seen by customers in the Experience Platform user interface.
        description:
          type: string
          example: Moviestar manages several instances across the globe for REST endpoints that our customers are provisioned for. Select your endpoint in the dropdown list.
          description: Provide a description for the custom field.
        isRequired:
          type: boolean
          example: true
          description: Indicates if this field is required in the destination setup workflow.
        default:
          type: object
        enum:
          type: array
          example:
          - US
          - EU
          - APAC
          - NZ
          description: Renders the custom field as a dropdown menu and lists the options available to the user.
          items:
            type: object
        pattern:
          type: string
          example: ^[A-Za-z]+$
          description: Enforces a pattern for the custom field, if needed. Use regular expressions to enforce a pattern. For example, if your customer IDs don’t include numbers or underscores, enter `^[A-Za-z]+$`` in this field.
        format:
          type: string
          example: password
          description: The format associated with the data. If you use `password` as format, Experience Platform will automatically treat the data field value as sensitive information and encrypt it.
    destinationDeliveryItem:
      type: object
      description: Settings related how customers authenticate to your destination.
      properties:
        authenticationRule:
          type: string
          example: CUSTOMER_AUTHENTICATION
          title: Authentication Rule
          description: 'Indicates how Experience Platform customers connect to your destination. <br><br> <ul> <li> Use `CUSTOMER_AUTHENTICATION` if Platform customers log into your system via OAuth 2, OAuth 1, a bearer token, or another method of authentication defined in `customerAuthenticationConfigurations`. `authenticationId` is not required for `CUSTOMER_AUTHENTICATION`. </li> <li> Use `PLATFORM_AUTHENTICATION` if there is a global authentication system between Adobe and your destination and the Platform customer does not need to provide any authentication credentials to connect to your destination. In this case, you must create a credentials object using the [Credentials configuration](http://www.adobe.com/go/destination-sdk-authentication-configuration-en) and use the ID of the credentials configuration object as the `authenticationId` below. </li> <li> Use `NONE` if no authentication is required to send data to your destination platform. </li> </ul> '
          enum:
          - CUSTOMER_AUTHENTICATION
          - PLATFORM_AUTHENTICATION
          - NONE
        authenticationId:
          type: string
          description: The `instanceId` of the credentials configuration object to use for authentication. This parameter is required when using `PLATFORM_AUTHENTICATION` to link your destination configuration to the credentials configuration. When using `CUSTOMER_AUTHENTICATION`, this parameter is not needed.
        destinationServerId:
          type: string
          example: 2307ec2b-4798-45a4-9239-5d0a2fb0ed67
          description: The `instanceId` of the destination server configuration used for this destination.
    identityNamespaces:
      type: object
      title: Identity Namespaces
      description: List of allowed identity namespaces.
      additionalProperties:
        $ref: '#/components/schemas/identityNamespace'
    configurableAggregation:
      title: Configurable Aggregation
      description: Required parameters to set up configurable aggregation.
      type: object
      properties:
        splitUserById:
          type: boolean
          example: false
          description: Use this flag if the call to the destination should be split by identity. Set this flag to true if your server only accepts one identity per call, for a given namespace.
        maxBatchAgeInSecs:
          type: integer
          example: 3000
          description: '<ul><li>*Minimum value: 1800*</li><li>*Maximum value: 3600*</li><li>See parameter in example configuration [here](https://experienceleague.adobe.com/docs/experience-platform/destinations/destination-sdk/functionality/destination-configuration.html?lang=en#example-configuration). Configure a value between the minimum and maximum accepted values. Together with `maxNumEventsInBatch`, this parameter determines how long Experience Platform should wait until sending an API call to your endpoint. <br> For example, if you use the maximum value for both parameters, Experience Platform will wait either 3600 seconds OR until there are 10.000 qualified profiles before making the API call, whichever happens first. </li></ul>'
        maxNumEventsInBatch:
          type: integer
          example: 5000
          description: '<ul><li>*Minimum value: 1000*</li><li>*Maximum value: 10000*</li><li>See parameter in example configuration [here](https://experienceleague.adobe.com/docs/experience-platform/destinations/destination-sdk/functionality/destination-configuration.html?lang=en#example-configuration). Configure a value between the minimum and maximum accepted values. For a description of this parameter, see `maxBatchAgeInSecs` just above.</li></ul> '
        aggregationKey:
          type: object
          description: 'Allows you to aggregate the exported profiles mapped to the destination based on the parameters below: 1.segment ID, 2.segment status,3. identity namespace.'
          properties:
            includeSegmentId:
              type: boolean
              example: true
              description: Set this to true if you want to group profiles exported to your destination by segment ID.
            includeSegmentStatus:
              type: boolean
              example: true
              description: You must set both `includeSegmentId:true` and `includeSegmentStatus:true` if you want to group profiles exported to your destination by segment ID AND segment status.
            includeIdentity:
              type: boolean
              example: true
              description: Set this to true if you want to group profiles exported to your destination by identity namespace.
            oneIdentityPerGroup:
              type: boolean
              example: false
              description: Use this parameter to specify if you want the exported profiles to be aggregated into groups of a single identity (GAID, IDFA, phone numbers, email, etc.)
            groups:
              type: array
              description: Create lists of identity groups if you want to group profiles exported to your destination by groups of identity namespace. For example, you could combine profiles that contain the IDFA and GAID mobile identifiers into one call to your destination and emails into another by using the configuration in the example.
              items:
                $ref: '#/components/schemas/IdentityGroup'
    IdentityGroup:
      type: object
      example:
      - namespaces:
        - IDFA
        - GAID
      - namespaces:
        - EMAIL
      properties:
        namespaces:
          type: array
          items:
            type: string
    customerAuthenticationConfiguration:
      type: object
      discriminator:
        propertyName: authType
      properties:
        authType:
          title: Customer Authentication Type
          example: BEARER
          description: Defines Customer Authentication type.
          type: string
          enum:
          - S3
          - SFTP_WITH_SSH_KEY
          - SFTP_WITH_PASSWORD
          - OAUTH1
          - OAUTH2
          - BASIC
          - BEARER
        options:
          type: object
          additionalProperties: {}
      required:
      - authType
    identityNamespace:
      type: object
      properties:
        acceptsAttributes:
          type: boolean
          example: 'true'
          description: Indicates if customers can map standard profile attributes to the identity that you are configuring.
        acceptsCustomNamespaces:
          type: boolean
          example: 'true'
          description: Indicates if customers can map identities belonging to [custom namespaces](https://experienceleague.adobe.com/docs/experience-platform/identity/namespaces.html?lang=en#manage-namespaces) to the identity that you are configuring.
        transformation:
          type: string
          description: Used, for example, when the Platform customer has plain email addresses as an attribute and your platform only accepts hashed emails. This is where you would provide the transformation that needs to be applied (for example, transform the email to lowercase, then hash).
        acceptedGlobalNamespaces:
          type: object
          example:
            Email: {}
            IDFA: {}
          description: 'Indicates which [standard identity namespaces](https://experienceleague.adobe.com/docs/experience-platform/identity/namespaces.html

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