Raw Export API

Content:

• Introduction
  • Versioning
  • Authentication
  • Date Format
  • Error Handling
• Reference
  • Destinations
    • Get all destinations and their details
    • Get a certain destination and its details
  • Event classes
  • Managing Exports
    • Get all exports and their details
    • Get a certain export's details
    • Request an export(events)
    • Request an export(users)
    • Cancel an export

Introduction

This asynchronous API enables export of user & event data from ActivatePro. 

Because sometimes events might come out of order or later than expected, to avoid inconsistencies or skipped data, we enforce a time gap for the data, that we export. With this setting we won't export any events with a timestamp later than 3 hours before export start time.

Versioning

The API version is defined in the header X-XNG-ApiVersion. To use the export API provide version 2.

Authentication

ActivatePro uses header authentication. To get your Master API key, please log in to the app and navigate to Settings. You will find it in the System setup -> API keys section in the Master API key value.

The following is an example of the format of an authentication header:

X-XNG-AuthToken: 1ab00011122c1234

Date Format

Dates and times are expressed in ISO8601 format in UTC (Coordinated Universal Time), with a special UTC designator ("Z") For more information please check here.

Please note, that Segment Buider in the ActivatePro App is using your local time zone. This means that if you'd like your Export API data to align with your Segment data, you need to use that same time zone when requesting your export via API.

Error Handling

When exporting data from ActivatePro, note the following error handling practices:

Resume or retry uploads that fail due to connection interruptions or any 5xx errors, including:

• 500 Internal Server Error
• 502 Bad gateway
• 503 Service Unavailable
• 504 Gateway Timeout

How to retry requests made to ActivatePro in case of errors:

• Use an exponential backoff strategy if an export request returns a 5xx server error. These errors can occur if a server is overloaded. Exponential backoff can alleviate such problems during periods of high request volume or heavy network traffic.
• Other kinds of requests should not be handled by exponential backoff but you can still retry a number of them. When retrying these requests, limit the number of times you retry them. For example your code could limit to ten retries or less before reporting the error to our team for investigation.

Reference

Destinations

These endpoints fetch export and callback destinations and their associated details.

In order to use the Export API you must provide an (S)FTP destination to which the export files will be uploaded. If you have already set up such an integration in the ActivatePro platform, these endpoints will return it with the type EXPORT. You can obtain this destination’s ID from the results of this call for use in requesting an export.

If you have not yet set up a suitable (S)FTP integration, follow these theps to create one in the ActivatePro App.

Optionally you can also use a callback destination. It's a webhook which will be called after your export is completed. Callback destination is a webhook integration, which should meet the following requirements:

• Method POST
• Content type JSON
• Basic authentication

Otherwise it will not appear in the destinations list. An attempt to use an invalid destination during export creation will lead to a validation error. 

The same as with EXPORT type destinations, the currently set-up destinations will be returned by these endpoints. You can use one of them or create a new one.

Here is the structure of webhook request body:

• exportId: ID of your exportexport
• DestinationId: export destination
• callbackDestinationId: export callback destination
• status: export status (FINISHED or FAILED)
• finishedAt: export end time

Example of a callback request:

 {
      "exportId": "5d90695a-c61f-453a-bd2d-7c4f0b8536cf",
      "exportDestinationId": "c88c0ddf-d3e3-4190-b1f8-df3dfbc7238f",
      "callbackDestinationId": "9f86d4c8-d902-497d-8d78-53ce184ac3ce",
      "status": "FINISHED",
      "finishedAt": "2019-08-07T12:24:06.772Z"
  }

GET https://api.crossengage.io/destination?type=

Content-Type:application/json
X-XNG-ApiVersion:2
X-XNG-AuthToken:YourAPIKey

Content-Type:application/json

[
  {
    "id": "b393489f-7d76-41c2-bb2f-f965ab997d2e",
    "name": "My destination name",
    "type": "EXPORT",
    "destination": "https://api-stg.xng.rocks/events",
    "createdAt": "2019-08-21T12:10:47Z",
    "updatedAt": "2019-08-21T12:11:47Z"
  }
]

GET https://api.crossengage.io/destination/id

Content-Type:application/json
X-XNG-ApiVersion:2
X-XNG-AuthToken:YourAPIKey

Content-Type:application/json

{
  "id": "b393489f-7d76-41c2-bb2f-f965ab997d2e",
  "name": "My destination name",
  "type": "EXPORT",
  "destination": "https://domain/events",
  "createdAt": "2019-08-21T12:10:47Z",
  "updatedAt": "2019-08-21T12:11:47Z"
}

Event classes

This endpoint provides information about mapping between legacy and new event types. If you want to filter events by their name when requesting an export, please find a matching new event name using this endpoint.

GET https://api.crossengage.io/event-class

Content-Type:application/json
X-XNG-ApiVersion:2
X-XNG-AuthToken:YourAPIKey

Content-Type:application/json

[
  {
    "name": "message.viewed",
    "legacyName": "mail.open",
    "channel": "mail"
  }
]

Managing Exports

These endpoints allow to fetch exports and their associated details, as well as to request or cancel new exports.

When you send an Export Request, our server will validate its parameters and return the request it will process. Because unknown and invalid parameters may be ignored, be sure to thoroughly check that the version of the request our server returns to you corresponds with your expectations. In some cases this initial processing may take several minutes, so your Request Export call may not be immediately visible via an Export Details call.

We limit the number of active exports to 2 per company. If you would like to run another export, you can either wait for one of the previously requested to finish, or cancel it manually.

Every export has one of the following statuses:

• WAITING - Your export request was processed by our system and is now waiting to be executed.
• RUNNING - Export is currently in progress. Depending on the size and the filters used, this could take as long as several hours.
• FINISHED - Export was completed. Requested data is exported to your chosen destination in multiple gzipped file parts using the id of the export for the file name definition
  e.g. 1ee25bc0-21aa-4759-8716-8397b6997e98.part1.json.gz, 1ee25bc0-21aa-4759-8716-8397b6997e98.part2.json.gz. Note that some of the exported files may be empty. This is a normal situation, which occurs as a result of work and data distribution between parallel workers for processing your export. The files will be located in an export folder. If this folder does not yet exists, it will be created.
• CANCELED - Export was canceled manually. Note that you can only cancel exports with statuses WAITING or RUNNING.

GET https://api.crossengage.io/export?status=FINISHED&pageNumber=3&pageSize=25

Content-Type:application/json
X-XNG-ApiVersion:2
X-XNG-AuthToken:YourAPIKey

Content-Type:application/json

[
  {
    "status": "WAITING",
    "outputFormat": "PARQUET",
    "requestedAt": "2019-09-04T15:30:53.298Z",
    "startedAt": "2019-09-04T15:36:53.298Z",
    "finishedAt": "2019-09-04T15:37:53.298Z",
    "id": "1ee25bc0-21aa-4759-8716-8397b6997e98",
    "exportDestinationId": "fec9ce18-a152-4fec-ab69-1b22606a015e",
    "callbackDestinationId": "4ce5fad8-4ec6-41ad-a5a0-fbf9b9ebdde0",
    "rawExport": true,
    "outputSuffix": "PARQUET",
    "segmentId": "67",
    "attributes": {
      "enabled": true,
      "filter": {
        "action": "INCLUDE",
        "names": [
          "traits.firstName",
          "traits.lastName",
          "traits.email"
        ]
      }
    },
    "events": {
      "enabled": false
    }
  }
]

GET https://api.crossengage.io/export/exportId

Content-Type:application/json
X-XNG-ApiVersion:2
X-XNG-AuthToken:YourAPIKey

Content-Type:application/json

{
  "status": "WAITING",
  "outputFormat": "PARQUET",
  "requestedAt": "2019-09-04T15:30:53.298Z",
  "startedAt": "2019-09-04T15:36:53.298Z",
  "finishedAt": "2019-09-04T15:37:53.298Z",
  "id": "1ee25bc0-21aa-4759-8716-8397b6997e98",
  "exportDestinationId": "fec9ce18-a152-4fec-ab69-1b22606a015e",
  "callbackDestinationId": "4ce5fad8-4ec6-41ad-a5a0-fbf9b9ebdde0",
  "rawExport": true,
  "outputSuffix": "PARQUET",
  "segmentId": "67",
  "attributes": {
    "enabled": true,
    "filter": {
      "action": "INCLUDE",
      "names": [
        "traits.firstName",
        "traits.lastName",
        "traits.email"
      ]
    }
  },
  "events": {
    "enabled": false
  }
}

POST https://api.crossengage.io/export

Content-Type:application/json
X-XNG-ApiVersion:2
X-XNG-AuthToken:YourAPIKey

{
  "status": "WAITING",
  "outputFormat": "PARQUET",
  "requestedAt": "2019-09-04T15:30:53.298Z",
  "startedAt": "2019-09-04T15:36:53.298Z",
  "finishedAt": "2019-09-04T15:37:53.298Z",
  "id": "1ee25bc0-21aa-4759-8716-8397b6997e98",
  "exportDestinationId": "fec9ce18-a152-4fec-ab69-1b22606a015e",
  "callbackDestinationId": "4ce5fad8-4ec6-41ad-a5a0-fbf9b9ebdde0",
  "rawExport": true,
  "outputSuffix": "PARQUET",
  "segmentId": "67",
  "attributes": {
    "enabled": false
  },
  "events": {
    "enabled": true,
     "filter": {
  	  "action": "INCLUDE",
	  "names": [
	    "order.item"
	  ]
	},  
    "interval": {
		"startDate": "2023-05-20T22:00:00Z",
		"endDate": "2023-05-21T23:59:59.999Z"
	}
  }
}

POST https://api.crossengage.io/export

Content-Type:application/json
X-XNG-ApiVersion:2
X-XNG-AuthToken:YourAPIKey

{
  "status": "WAITING",
  "outputFormat": "PARQUET",
  "requestedAt": "2019-09-04T15:30:53.298Z",
  "startedAt": "2019-09-04T15:36:53.298Z",
  "finishedAt": "2019-09-04T15:37:53.298Z",
  "id": "1ee25bc0-21aa-4759-8716-8397b6997e98",
  "exportDestinationId": "fec9ce18-a152-4fec-ab69-1b22606a015e",
  "callbackDestinationId": "4ce5fad8-4ec6-41ad-a5a0-fbf9b9ebdde0",
  "rawExport": true,
  "outputSuffix": "PARQUET",
  "segmentId": "67",
  "attributes": {
    "enabled": true,
    "filter": {
      "action": "INCLUDE",
      "names": [
        "traits.firstName",
        "traits.lastName",
        "traits.email"
      ]
    }
  },
  "events": {
    "enabled": false
  }
}

DELETE https://api.crossengage.io/export/exportId

Content-Type:application/json
X-XNG-ApiVersion:2
X-XNG-AuthToken:YourAPIKey