{"openapi":"3.0.1","info":{"title":"Data Firehose","description":"**Note: This is in private preview and should not be used.**\n\nCreate, retrieve, update, and delete Data Firehose configurations. Use this\nAPI to define which events to stream, set the sync frequency, configure the\ntarget storage platform (Amazon S3, Azure Blob Storage, FTPS, SFTP, or\nGoogle 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":"-----BEGIN PRIVATE KEY-----\\nMI……s=\\n-----END PRIVATE KEY-----\\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":"-----BEGIN RSA PRIVATE KEY-----\\nMIIEowIBAAKCAQEA2+/hDfK5sxpE2djWfdrdLiRjIo28WbcsfWMu4hty58kaSF5O……\\n-----END RSA PRIVATE KEY-----"}},"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"}}}}