openapi: 3.0.1 info: title: Data Firehose 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: 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 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 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' 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. 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 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 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 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 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 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 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 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 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' 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. 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 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. 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 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 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. 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 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 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. 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 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 securitySchemes: basicAuth: type: http scheme: basic