Dotdigital Data Firehose API

openapi: 3.2.0
info:
  title: Data Firehose API
  description: '**Note: This is in private preview and should not be used.**


    Create, retrieve, update, and delete Data Firehose configurations. Use this

    API to define which events to stream, set the sync frequency, configure the

    target storage platform (Amazon S3, Azure Blob Storage, FTPS, SFTP, or

    Google Cloud Storage), and enable or disable a configuration.'
  version: 3.0.1
servers:
- url: https://{region}-api.dotdigital.com
  variables:
    region:
      description: The Dotdigital region id your account belongs to
      enum:
      - r1
      - r2
      - r3
      default: r1
tags:
- name: Data Firehose
paths:
  /data-firehose/v3/configurations/{id}:
    get:
      tags:
      - Data Firehose
      summary: Get configuration
      description: "Gets a Data Firehose configuration. \n"
      operationId: getConfiguration
      parameters:
      - name: id
        in: path
        description: The Data Firehose configuration id to delete
        required: true
        schema:
          type: string
        example: '1234'
      responses:
        '200':
          description: Configuration retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/fireshoseConfiguration'
        '400':
          description: Bad request, you have an error in the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Configuration not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                errorCode: dataFirehose:configNotFound
                description: The Data Firehose configuration id `YOUR ID` was not found!
      deprecated: false
      security:
      - basicAuth: []
    put:
      tags:
      - Data Firehose
      summary: Update configuration
      description: Updates a Data Firehose configuration with new details.
      operationId: updateConfiguration
      parameters:
      - name: id
        in: path
        description: The Data Firehose configuration id you want to update.
        required: true
        schema:
          type: string
        example: '1234'
      - name: x-ddg-integration-token
        in: header
        description: If you are a partner of Dotdigital and have a verified integration then include your integration tracking token here.
        required: false
        schema:
          pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
          type: string
        example: 54639c53-af3f-4e81-843d-d2486fc76fff
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/fireshoseConfigurationRequest'
            examples: {}
      responses:
        '200':
          description: Updated Data Firehose configuration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/fireshoseConfiguration'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Configuration not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                errorCode: dataFirehose:configNotFound
                description: The Data Firehose configuration id `YOUR ID` was not found!
      deprecated: false
      security:
      - basicAuth: []
    delete:
      tags:
      - Data Firehose
      summary: Delete configuration
      description: "Deletes a Data Firehose configuration. \nIf data sync is in progress returns 409.\n\n_Note: Once a configuration deleted it cannot be restored, this is a destructive call!_"
      operationId: deleteConfiguration
      parameters:
      - name: id
        in: path
        description: The Data Firehose configuration id to delete
        required: true
        schema:
          type: string
        example: '1234'
      responses:
        '204':
          description: Configuration deleted successfully
        '400':
          description: Bad request, you have an error in the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Configuration not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                errorCode: dataFirehose:configNotFound
                description: The Data Firehose configuration id `YOUR ID` was not found!
        '409':
          description: Cannot delete data sync in progress
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                errorCode: dataFirehose:syncInProgress
                description: The Data Firehose configuration is currently syncing so cannot be deleted.
      deprecated: false
      security:
      - basicAuth: []
  /data-firehose/v3/configurations/{id}/status/{newStatus}:
    put:
      tags:
      - Data Firehose
      summary: Update configuration status
      description: Updates the status of a Data Firehose configuration.
      operationId: updateStatus
      parameters:
      - name: id
        in: path
        description: The Data Firehose configuration id you want to update.
        required: true
        schema:
          type: string
        example: '1234'
      - name: newStatus
        in: path
        description: The new status for the configuration.
        required: true
        schema:
          type: string
          enum:
          - enabled
          - disabled
        example: enabled
      - name: x-ddg-integration-token
        in: header
        description: If you are a partner of Dotdigital and have a verified integration then include your integration tracking token here.
        required: false
        schema:
          type: string
        example: 54639c53-af3f-4e81-843d-d2486fc76fff
      responses:
        '204':
          description: Status updated
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Configuration not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                errorCode: dataFirehose:configNotFound
                description: The Data Firehose configuration id `YOUR ID` was not found!
      deprecated: false
      security:
      - basicAuth: []
  /data-firehose/v3/configurations:
    post:
      tags:
      - Data Firehose
      summary: Add configuration
      description: Adds a new Data Firehose configuration.
      operationId: addConfiguration
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/fireshoseConfigurationRequest'
            examples: {}
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/fireshoseConfiguration'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties: {}
              example:
                errorCode: events:badJson
                description: The request JSON is badly formed
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      deprecated: false
      security:
      - basicAuth: []
components:
  schemas:
    sftpPrivateKey:
      required:
      - authentication
      - configuration
      - platform
      type: object
      properties:
        platform:
          type: string
          enum:
          - sftp
        configuration:
          $ref: '#/components/schemas/sftpPassword_configuration'
        authentication:
          $ref: '#/components/schemas/sftpPrivateKey_authentication'
      additionalProperties: false
      description: Amazon S3 storage
    sftpPassword_configuration:
      required:
      - addAccountIdToPath
      - folderPath
      - host
      - port
      type: object
      properties:
        folderPath:
          type: string
          description: The folder path on the server.
          example: ./events/dotdigital
        port:
          type: integer
          description: The TCP port to use for the connections.
          example: 22
        host:
          type: string
          description: The hostname or IP address of the server.
          example: my-sftp-server.com
        addAccountIdToPath:
          type: boolean
          description: Add the account id as a suffix to the path for identification purposes.
      additionalProperties: false
      description: The configuration parameters for the storage.
    smsFailedEvent:
      required:
      - eventType
      type: object
      properties:
        eventType:
          type: string
          description: The event type.
          enum:
          - sms.failed
        filters:
          maxItems: 100
          minItems: 1
          type: array
          description: Optional additional filters for the event.
          items:
            type: string
            enum:
            - failed
            - expired
            - deleted
            - softBounced
            - hardBounced
            - skipped
      additionalProperties: false
    googleCloudStorage_configuration:
      required:
      - addAccountIdToPath
      - bucketName
      - folderPath
      type: object
      properties:
        folderPath:
          type: string
          description: The specific folder path within the GCS bucket where the data will be stored.
          example: dataPool1
        bucketName:
          type: string
          description: The GCS bucket name where the data will be stored.
          example: myBucketName
        addAccountIdToPath:
          type: boolean
          description: Add the account id as a suffix to the path for identification purposes.
      additionalProperties: false
      description: The configuration parameters for the storage.
    googleCloudStorage_authentication:
      required:
      - authProviderX509CertUrl
      - authUri
      - clientEmail
      - clientId
      - clientX509CertUrl
      - privateKey
      - privateKeyId
      - projectId
      - tokenUri
      - type
      - universeDomain
      type: object
      properties:
        type:
          type: string
          description: Value taken from Service account key "type" property.
          example: service_account
        projectId:
          type: string
          description: Value taken from Service account key "project_id" property.
          example: project1
        privateKeyId:
          type: string
          description: Value taken from Service account key "private_key_id" property.
          example: b396ebf0d37d23a2ccade
        privateKey:
          type: string
          description: Value taken from Service account key "private_key" property.
          example: REDACTED_PRIVATE_KEY_EXAMPLE\n
        clientEmail:
          type: string
          description: Value taken from Service account key "client_email" property.
          format: email
          example: test@server.iam.gserviceaccount.com
        clientId:
          type: string
          description: Value taken from Service account key "client_id" property.
          example: '167712385160818712314'
        authUri:
          type: string
          description: Value taken from Service account key "auth_uri" property.
          format: uri
          example: https://accounts.google.com/o/oauth2/auth
        tokenUri:
          type: string
          description: Value taken from Service account key "token_uri" property.
          format: uri
          example: https://oauth2.googleapis.com/token
        authProviderX509CertUrl:
          type: string
          description: Value taken from Service account key "auth_provider_x509_cert_url" property.
          format: uri
          example: https://www.googleapis.com/oauth2/v1/certs
        clientX509CertUrl:
          type: string
          description: Value taken from Service account key "client_x509_cert_url" property.
          format: uri
          example: https://www.googleapis.com/robot/v1/metadata/x509/server.iam.gserviceaccount.com
        universeDomain:
          type: string
          description: Value taken from Service account key "universe_domain" property.
          example: googleapis.com
      additionalProperties: false
      description: The authentication details for the platform
    errorResponse_details:
      required:
      - description
      - item
      type: object
      properties:
        item:
          type: string
          description: Item the error is associated with, for example, field name, unique identifier for an entity or item in batch
        description:
          type: string
          description: Description of the error
    sftpPrivateKey_authentication:
      required:
      - authType
      - privateKey
      - username
      type: object
      properties:
        authType:
          type: string
          description: The authentication type.
          enum:
          - privateKey
        username:
          type: string
          description: Username to authenticate with.
          example: myUser
        privateKey:
          type: string
          description: SSH private key to authenticate with.
          example: REDACTED_PRIVATE_KEY_EXAMPLE
      additionalProperties: false
      description: The authentication details for the platform
    azureBlobSas_authentication:
      required:
      - authType
      - sasToken
      type: object
      properties:
        authType:
          type: string
          description: The authentication type
          enum:
          - sasToken
        sasToken:
          type: string
          description: Shared access signature to use to authenticate with the Azure service.
          example: 2021-10-04&se=2023-03-20T11%3A20%3A45Z&sr=b&sp=r&sig=M5GaoRgyIWcLMMfggqfZ9pI01dZLyFD0Em5WdCNsUuk%3D
      additionalProperties: false
      description: The authentication details for the platform
    azureBlobSas:
      required:
      - authentication
      - configuration
      - platform
      type: object
      properties:
        platform:
          type: string
          enum:
          - azureBlobStorage
        configuration:
          $ref: '#/components/schemas/azureBlobOauth_configuration'
        authentication:
          $ref: '#/components/schemas/azureBlobSas_authentication'
      additionalProperties: false
      description: Amazon S3 storage
    googleCloudStorage:
      required:
      - authentication
      - configuration
      - platform
      type: object
      properties:
        platform:
          type: string
          enum:
          - googleCloudStorage
        configuration:
          $ref: '#/components/schemas/googleCloudStorage_configuration'
        authentication:
          $ref: '#/components/schemas/googleCloudStorage_authentication'
      additionalProperties: false
      description: Amazon S3 storage
    azureBlobOauth_authentication:
      required:
      - authType
      - clientId
      - clientSecret
      - tenantId
      type: object
      properties:
        authType:
          type: string
          description: The authentication type
          enum:
          - oAuth2
        tenantId:
          type: string
          description: The Microsoft Entra tenant (directory) ID of the service principal.
          example: de249954-0df3-4661-acde-1e1be9d73fd6
        clientId:
          type: string
          description: The client (application) ID of the service principal.
          example: key123123
        clientSecret:
          type: string
          description: A client secret that was generated for the App Registration used to authenticate the client.
          example: some-secret
      additionalProperties: false
      description: The authentication details for the platform
    azureBlobOauth_configuration:
      required:
      - accountName
      - addAccountIdToPath
      - containerName
      - folderPath
      type: object
      properties:
        folderPath:
          type: string
          description: The specific folder path within the Blob Storage where the data will be stored.
          example: dataPool1
        accountName:
          type: string
          description: The storage account name where the data will be stored.
          format: uri
          example: eu-central-1
        containerName:
          type: string
          description: The container name within storage account where data will be stored.
          example: events/test
        addAccountIdToPath:
          type: boolean
          description: Add the account id as a suffix to the path for identification purposes.
      additionalProperties: false
      description: The configuration parameters for the storage.
    ftpsPassword_authentication:
      required:
      - authType
      - password
      - username
      type: object
      properties:
        authType:
          type: string
          description: The authentication type.
          enum:
          - password
        username:
          type: string
          description: Username to authenticate with.
          example: myUser
        password:
          type: string
          description: Password.
          example: sssh don't tell
      additionalProperties: false
      description: The authentication details for the platform
    ftpsPassword_configuration:
      required:
      - addAccountIdToPath
      - folderPath
      - host
      - port
      type: object
      properties:
        folderPath:
          type: string
          description: The folder path on the server.
          example: ./events/dotdigital
        port:
          type: integer
          description: The TCP port to use for the connections.
          example: 21
        host:
          type: string
          description: The hostname or IP address of the server.
          example: my-sftp-server.com
        addAccountIdToPath:
          type: boolean
          description: Add the account id as a suffix to the path for identification purposes.
      additionalProperties: false
      description: The configuration parameters for the storage.
    fireshoseConfigurationRequest:
      required:
      - alertsConfiguration
      - events
      - frequency
      - target
      type: object
      properties:
        events:
          maxItems: 100
          minItems: 1
          type: array
          description: The events you want included in your data flow.
          items:
            oneOf:
            - $ref: '#/components/schemas/unfilteredEvents'
            - $ref: '#/components/schemas/emailFailedEvent'
            - $ref: '#/components/schemas/transactionalEmailFailedEvent'
            - $ref: '#/components/schemas/smsFailedEvent'
        frequency:
          type: string
          description: The frequency of the data sync.
          enum:
          - daily
          - hourly
          - fifteenMinutes
        target:
          description: The target platform to send data to.
          oneOf:
          - $ref: '#/components/schemas/amazonS3sas'
          - $ref: '#/components/schemas/azureBlobOauth'
          - $ref: '#/components/schemas/azureBlobSas'
          - $ref: '#/components/schemas/ftpsPassword'
          - $ref: '#/components/schemas/googleCloudStorage'
          - $ref: '#/components/schemas/sftpPassword'
          - $ref: '#/components/schemas/sftpPrivateKey'
        alertsConfiguration:
          description: Alert options to use if we detect issues with the subscription.
          example:
            alertChannels: email
            email: hi@emailsim.io
          oneOf:
          - required:
            - alertChannels
            type: object
            properties:
              alertChannels:
                type: string
                description: The type(s) of channels to be alerted on.
                enum:
                - none
            description: No alerts
          - required:
            - alertChannels
            type: object
            properties:
              alertChannels:
                type: string
                description: The type(s) of channels to be alerted on.
                enum:
                - inApp
            description: In app alerts only
          - required:
            - alertChannels
            - email
            type: object
            properties:
              alertChannels:
                type: string
                description: The type(s) of channels to be alerted on.
                enum:
                - email
              email:
                type: string
                description: The email address to send alerts regarding this subscription to.
                format: email
                example: alerts@emailsim.io
            description: Email alerts only
          - required:
            - alertChannels
            - email
            type: object
            properties:
              alertChannels:
                type: string
                description: The type(s) of channels to be alerted on.
                enum:
                - emailAndInApp
              email:
                type: string
                description: The email address to send alerts regarding this subscription to.
                format: email
                example: alerts@emailsim.io
            description: Email and in-app alerts
      additionalProperties: false
      description: A configuration for Data Firehose.
    ftpsPassword:
      required:
      - authentication
      - configuration
      - platform
      type: object
      properties:
        platform:
          type: string
          enum:
          - ftps
        configuration:
          $ref: '#/components/schemas/ftpsPassword_configuration'
        authentication:
          $ref: '#/components/schemas/ftpsPassword_authentication'
      additionalProperties: false
      description: Amazon S3 storage
    azureBlobOauth:
      required:
      - authentication
      - configuration
      - platform
      type: object
      properties:
        platform:
          type: string
          enum:
          - azureBlobStorage
        configuration:
          $ref: '#/components/schemas/azureBlobOauth_configuration'
        authentication:
          $ref: '#/components/schemas/azureBlobOauth_authentication'
      additionalProperties: false
      description: Amazon S3 storage
    sftpPassword:
      required:
      - authentication
      - configuration
      - platform
      type: object
      properties:
        platform:
          type: string
          enum:
          - sftp
        configuration:
          $ref: '#/components/schemas/sftpPassword_configuration'
        authentication:
          $ref: '#/components/schemas/ftpsPassword_authentication'
      additionalProperties: false
      description: Amazon S3 storage
    amazonS3sas_configuration:
      required:
      - addAccountIdToPath
      - bucketName
      - folderPath
      - regionEndpoint
      type: object
      properties:
        bucketName:
          type: string
          description: The S3 bucket name
          example: dataPool1
        regionEndpoint:
          type: string
          description: The regional endpoint URL for the S3 service.
          format: uri
          example: eu-central-1
        folderPath:
          type: string
          description: The folder path within the bucket.
          example: events/test
        addAccountIdToPath:
          type: boolean
          description: Add the account id as a suffix to the path for identification purposes.
      additionalProperties: false
      description: The configuration parameters for the storage.
    errorResponse:
      required:
      - description
      - errorCode
      type: object
      properties:
        errorCode:
          type: string
          description: Unique error code
        description:
          type: string
          description: Description of the issue
        details:
          type: array
          items:
            $ref: '#/components/schemas/errorResponse_details'
    unfilteredEvents:
      required:
      - eventType
      type: object
      properties:
        eventType:
          type: string
          description: The event type.
          enum:
          - email.click
          - email.open
          - email.send
          - email.view
          - email.doubleOptIn
          - email.unsubscribed
          - email.ispComplained
          - landingPage.view
          - page.view
          - pushNotification.error
          - pushNotification.send
          - sms.click
          - sms.send
          - sms.unsubscribed
          - sms.delivered
          - sms.reply
          - transactional.click
          - transactional.open
          - campaign.send
          - email.reply
          - interaction.pushClick
          - interaction.socialShare
          - sms.remove
          - transactional.emailCampaignSend
      additionalProperties: false
    fireshoseConfiguration:
      allOf:
      - required:
        - id
        - status
        type: object
        properties:
          id:
            type: string
            description: The unique identifier for the Data Firehose configuration.
          status:
            type: string
            description: The status of this sync configuration
            enum:
            - enabled
            - disabled
        additionalProperties: false
      - $ref: '#/components/schemas/fireshoseConfigurationRequest'
    amazonS3sas:
      required:
      - authentication
      - configuration
      - platform
      type: object
      properties:
        platform:
          type: string
          enum:
          - amazonS3
        configuration:
          $ref: '#/components/schemas/amazonS3sas_configuration'
        authentication:
          $ref: '#/components/schemas/amazonS3sas_authentication'
      additionalProperties: false
      description: Amazon S3 storage
    transactionalEmailFailedEvent:
      required:
      - eventType
      type: object
      properties:
        eventType:
          type: string
          description: The event type.
          enum:
          - transactional.emailFailed
        filters:
          maxItems: 100
          minItems: 1
          type: array
          description: Optional additional filters for the event.
          items:
            type: string
            enum:
            - hardBounced
            - softBounced
            - mailBlocked
      additionalProperties: false
    emailFailedEvent:
      required:
      - eventType
      type: object
      properties:
        eventType:
          type: string
          description: The event type.
          enum:
          - email.failed
        filters:
          maxItems: 100
          minItems: 1
          type: array
          description: Optional additional filters for the event.
          items:
            type: string
            enum:
            - hardBounced
            - softBounced
            - mailBlocked
      additionalProperties: false
    amazonS3sas_authentication:
      required:
      - accessKey
      - authType
      - secretAccessKey
      type: object
      properties:
        authType:
          type: string
          description: The authentication type
          enum:
          - sas
        accessKey:
          type: string
          description: The access key for the S3 storage
          example: key123123
        secretAccessKey:
          type: string
          description: The secret for the access key for the S3 storage
          example: some-secret
      additionalProperties: false
      description: The authentication details for the platform
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic