Dataviews

The CJA Dataviews APIs allow you to retrieve, create, or update dataviews programmatically through Adobe Developer. These APIs use the same data and methods that Adobe uses inside the product UI. See Dataviews in the Customer Journey Analytics guide for more information.

The endpoints described in this guide are routed through analytics.adobe.io. To use them, you will need to first create a client with access to Customer Journey Analytics APIs. For more information, refer to Getting started with the Customer Journey Analytics API.

data-variant=info

data-slots=text

This guide includes instructions for using the following endpoints:

• GET multiple data views: Retrieves a list of data views for a specified company
• GET a single data view: Retrieves information for a single data view
• POST validate a data view: Checks a data view for correct fields before creating
• POST create a data view: Creates a data view with a JSON payload for a specified company
• PUT copy a data view: Copies a data view
• PUT modify a data view: Modifies or updates a data view with new data
• DELETE a data view: Removes a data view

GET multiple data views

Use this endpoint to retrieve multiple data views associated with a company.

GET https://cja.adobe.io/data/dataviews

Request and response examples

Click the Request tab in the following example to see a cURL request for this endpoint. Click the Response tab to see a successful JSON response for the request.

data-slots=heading, code

data-repeat=2

data-languages=CURL,JSON

curl -X GET "https://cja.adobe.io/data/dataviews?expansion=name%2Cowner%2Corganization%2Cdescription&limit=3&page=0" \
-H "x-api-key: {API_KEY}" \
-H "x-gw-ims-org-id: {IMS_ORG_ID}" \
-H "Authorization: Bearer {AUTHORIZATION_TOKEN}"

{
    "content": [
        {
            "name": "Example 1 Data View",
            "description": "Campaign list 1",
            "owner": {
                "imsUserId": "{IMS_USER_ID}",
                "ownerId": "{OWNER_ID}",
                "name": "Example name 1",
                "type": "imsUser"
            },
            "organization": "{IMS_ORG_ID}",
            "systemUserOwned": false,
            "id": "dv_1de9ac146e674b139222222"
        },
        {
            "name": "Example 2 Data View",
            "description": "Campaign list 2",
            "owner": {
                "imsUserId": "{IMS_USER_ID}",
                "ownerId": "{OWNER_ID}",
                "name": "Example name 2",
                "type": "imsUser"
            },
            "organization": "{IMS_ORG_ID}",
            "systemUserOwned": false,
            "id": "dv_2de9ac146e674b139222223"
        },
        {
            "name": "Example 3 Data View",
            "description": "Campaign list 3",
            "owner": {
                "imsUserId": "{IMS_USER_ID}",
                "ownerId": "{OWNER_ID}",
                "name": "Example name 3",
                "type": "imsUser"
            },
            "organization": "{IMS_ORG_ID}",
            "systemUserOwned": false,
            "id": "dv_3de9ac146e674b139222224"
        }
    ],
    "number": 0,
    "totalElements": 1170,
    "totalPages": 390,
    "numberOfElements": 3,
    "firstPage": true,
    "lastPage": false,
    "sort": null,
    "size": 3
}

Request example details

The example above requests the following:

• The expansion parameter values for name, owner, organization, and description of the data views to be included in the response.
• The limit of results per page to be 3.
• The first page to be shown is 0.

Response example details

The example response above shows the following:

• The first result, Example 1 Data View is the data view name; Example name 1 is the name of the owner; and Campaign list 1 is the description. These values are returned as requested expansion parameters.
• The IDs for the data views are dv_1de9ac146e674b139222222, dv_2de9ac146e674b139222223, and dv_3de9ac146e674b139222224.
• The "number": 0 refers to the displayed page, or the first page.
• The numberOfElements confirms our request that the results displayed per page is 3.
• The totalElements of all the data views for the specified organization is 1170.
• The totalPages of data views is 390 where the numberOfElements per page is 3.

Request parameters

Response parameters

GET a single data view

Use this endpoint to retrieve data associated with a specific data view.

GET https://cja.adobe.io/data/dataviews/{DATA_VIEW_ID}

Request and response examples

Click the Request tab in the following example to see a cURL request for this endpoint. Click the Response tab to see a successful JSON response for the request.

data-slots=heading, code

data-repeat=2

data-languages=CURL,JSON

curl -X GET "https://cja.adobe.io/data/dataviews/dv_150a049f5d02785bacxxxxxx?expansion=name%2Cowner%2Cdescription%2CparentDataGroupId%2CtimezoneDesignator%2CexternalData" \
-H "x-api-key: {API_KEY}" \
-H "x-gw-ims-org-id: {IMS_ORG_ID}" \
-H "Authorization: Bearer {AUTHORIZATION_TOKEN}"

{
    "name": "Example Data View 1",
    "description": "Example Data View",
    "owner": {
        "imsUserId": "{IMS_USER_ID}",
        "ownerId": "{OWNER_ID}",
        "name": "Example name 1",
        "type": "imsUser"
    },
    "parentDataGroupId": "dg_c590c1e0-0cb0-11ea-a9a5-19370exxxxxx",
    "timezoneDesignator": "US/Mountain",
    "externalData": {
        "externalParentId": "c590c1e0-0cb0-11ea-a9a5-19370exxxxxx"
    },
    "id": "dv_150a049f5d02785bacxxxxxx"
}

Request example details

The example above requests the expansion parameter values for name, owner, description, parentDataGroupId, timezoneDesignator, and externalData for data view dv_150a049f5d02785bacxxxxxx.

Response example details

The example response above shows the following for data view dv_150a049f5d02785bacxxxxxx:

• Example Data View 1 as the name.
• Example Data View as the description.
• Example name 1 as the name for the owner.
• dg_c590c1e0-0cb0-11ea-a9a5-19370exxxxxx as the parentDataGroupId.
• US/Mountain as the timezoneDesignator.
• c590c1e0-0cb0-11ea-a9a5-19370exxxxxx as theexternalData.

Request parameters

Response parameters

POST Validate a data view

Use this endpoint to validate a data view structure before using other POST or PUT methods. You can use this as a check to make sure your current data structure is valid before it is final.

POST https://cja.adobe.io/data/dataviews/validate

Request and response examples

Click the Request tab in the following example to see a cURL request for this endpoint. Click the Response tab to see a successful JSON response for the request.

data-slots=heading, code

data-repeat=2

data-languages=CURL,JSON

curl -X POST "https://cja.adobe.io/data/dataviews/validate" \
-H "x-api-key: {API_KEY}" \
-H "x-gw-ims-org-id: {IMS_ORG_ID}" \
-H "Authorization: Bearer {AUTHORIZATION_TOKEN}"\
-H "Content-Type: application/json" \
--data-raw '{
    "name": "testView",
    "description": "A Test Data View",
    "owner": {
        "imsUserId": "{IMS_USER_ID}",
        "ownerId": "{OWNER_ID}",
        "name": "null null",
        "type": "imsUser"
    },
    "isDeleted": false,
    "parentDataGroupId": "{PARENT_DATA_GROUP_ID}",
    "organization": "{IMS_ORG_ID}",
    "modifiedBy": "{IMS_USER_ID}",
    "sessionDefinition": [
        {
            "numPeriods": 15,
            "granularity": "minute",
            "func": "inactivity",
            "events": [
                "string"
            ]
        }
    ],
    "externalData": {
        "externalParentId": "{EXTERNAL_PARENT_ID}"
    }
}'

{
    "valid": false,
    "message": "The following fields are required: [timezoneDesignator] "
}

Request example details

The example above requests a validation for the data structure shown in the body of the request. No data view ID is supplied.

Response example details

The example above shows a false response for an invalid data structure. The message includes the missing field timeZoneDesignator required for a valid structure. If a structure is valid, it returns the following:

{
    "valid": true,
}

Request parameters

The request parameters are dependent upon the structure supplied for validation. The following table shows the parameters shown in the example data structure.

Response parameters

POST create a data view

Use this endpoint to create a data view using a JSON payload.

POST https://cja.adobe.io/data/dataviews

Request and response examples

Click the Request tab in the following example to see a cURL request for this endpoint. Click the Response tab to see a successful JSON response for the request.

data-slots=heading, code

data-repeat=2

data-languages=CURL,JSON

curl -X POST "https://cja.adobe.io/data/dataviews?expansion=name%2Cdescription%2CparentDataGroupId%2CcurrentTimezoneOffset%2CtimezoneDesignator%2Corganization%2CsessionDefinition%2CexternalData" \
-H "x-api-key: {API_KEY}" \
-H "x-gw-ims-org-id: {IMS_ORG_ID}" \
-H "Authorization: Bearer {AUTHORIZATION_TOKEN}"\
-H "Content-Type: application/json" \
--data-raw '{
  "name": "testView",
  "description": "Test Data View",
  "parentDataGroupId": "dg_xxxxxxx-0cb0-11ea-a9a5-xxxxxxxxxxx",
  "timezoneDesignator": "US/Mountain",
  "sessionDefinition": [
    {
      "numPeriods": 15,
      "granularity": "MINUTE",
      "func": "INACTIVITY",
      "events": [
        "string"
      ]
    }
  ],
  "organization": "{IMS_ORG_ID}",
  "externalData": {
    "externalParentId": "xxxxxxx-0cb0-11ea-a9a5-xxxxxxxxxxx"
  }
}'

{
    "name": "testView",
    "description": "Test Data View",
    "parentDataGroupId": "dg_xxxxxxx-0cb0-11ea-a9a5-xxxxxxxxxxx",
    "currentTimezoneOffset": -6.0,
    "timezoneDesignator": "US/Mountain",
    "organization": "{IMS_ORG_ID}",
    "sessionDefinition": [
        {
            "numPeriods": 15,
            "granularity": "minute",
            "func": "inactivity",
            "events": [
                "string"
            ]
        }
    ],
    "externalData": {
        "externalParentId": "{EXTERNAL_PARENT_ID}"
    },
    "id": "dv_650a049f5d02785bacxxxxxx"
}

Request example details

The example above requests the following:

• Specifies the name of the data view as testView.
• The parentDataGroupId is specified as dg_xxxxxxx-0cb0-11ea-a9a5-xxxxxxxxxxx.
• Specifies the sessionDefinition to consist of 15 one-minute periods of inactivity before ending.

Response example details

The response example above shows the following:

• The id of the created data view is dv_650a049f5d02785bacxxxxxx.
• A confirmation of the sessionDefinition parameter values, as described in the request details.

Request parameters

Request body

Response parameters

The response parameters are the same as the request parameters. See the preceding table for descriptions.

PUT Copy a data view

Use this endpoint to copy a data view.

PUT https://cja.adobe.io/data/dataviews/copy/{DATA_VIEW_ID}

Request and response examples

Click the Request tab in the following example to see a cURL request for this endpoint. Click the Response tab to see a successful JSON response for the request.

data-slots=heading, code

data-repeat=2

data-languages=CURL,JSON

curl -X PUT "https://cja.adobe.io/data/dataviews/copy/dv_650a049f5d02785bacxxxxxx?expansion=name%2Cdescription%2Cowner%2CcreatedDate" \
-H "x-api-key: {API_KEY}" \
-H "x-gw-ims-org-id: {IMS_ORG_ID}" \
-H "Authorization: Bearer {AUTHORIZATION_TOKEN}"\

{
    "name": "testView (Copy)",
    "description": "A test data view",
    "owner": {
        "imsUserId": "Copy_requester@example.com",
        "ownerId": "Copy_requester@example.com",
        "name": "null null",
        "type": "imsUser"
    },
    "createdDate": "20XX-09-19T20:20:11Z",
    "componentType": "dataView",
    "id": "dv_111b123g4e63481redxxxxxx"
}

Request example details

The example above shows the following information:

• A request to copy the data view dv_650a049f5d02785bacxxxxxx.
• A request to return the name, description, owner, and createdDate of the successful copy.

Response example details

The example response above shows the following information:

• The name of the new copy is the same as the original with (Copy) added to it.
• The description is the same as the original.
• The imsUserId and ownerId reflect the information of the user requesting the copy. The original owner information does not persist to the copy.
• The new data view ID dv_111b123g4e63481redxxxxxx is provided for the copy.

Request parameters

Response parameters

PUT Modify a data view

Use this endpoint to modify a data view by sending a JSON structure containing the values to be changed.

PUT https://cja.adobe.io/data/dataviews/{DATA_VIEW_ID}

Request and response examples

In the following examples, the dv_650a049f5d02785bacxxxxxx data view created above is modified so that the numPeriods in sessionDefinition is set to 30 instead of 15.

Click the Request tab in the following example to see a cURL request for this endpoint. Click the Response tab to see a successful JSON response for the request.

data-slots=heading, code

data-repeat=2

data-languages=CURL,JSON

curl -X PUT "https://cja.adobe.io/data/dataviews/dv_650a049f5d02785bacxxxxxx?expansion=name%2Cmodified" \
-H "x-api-key: {API_KEY}" \
-H "x-gw-ims-org-id: {IMS_ORG_ID}" \
-H "Authorization: Bearer {AUTHORIZATION_TOKEN}"\
-H "Content-Type: application/json" \
-d '{
  "sessionDefinition": [
    {
      "numPeriods": 30,
      "granularity": "MINUTE",
      "func": "INACTIVITY",
      "events": [
        "string"
      ]
    }
  ]
}'

{
    "name": "testView",
    "sessionDefinition": [
        {
            "numPeriods": 30,
            "granularity": "minute",
            "func": "inactivity",
            "events": [
                "string"
            ]
        }
    ],
    "id": "dv_650a049f5d02785bacxxxxxx",
    "modifiedDate": "2023-09-19T20:32:20Z",
    "modifiedBy": "{IMS_USER_ID}"
}

Request example details

The example request above modifies the numPerioPeriods in the data view dv_650a049f5d02785bacxxxxxx to 30 minute periods of inactivity before ending.

Response example details

The example response above shows the following:

• The updated numPeriods value of 30 in the sessionDefintion for the data view.
• The name of the data view and the modification details, as specified in the request.

Request parameters

Response parameters

DELETE a data view

Use this endpoint to remove a data view.

DELETE https://cja.adobe.io/data/dataviews/{DATA_VIEW_ID}

Request and response examples

Click the Request tab in the following example to see a cURL request for this endpoint. Click the Response tab to see a successful JSON response for the request.

data-slots=heading, code

data-repeat=2

data-languages=CURL,JSON

curl -X DELETE "https://cja.adobe.io/data/dataviews/dv_650a049f5d02785bacxxxxxx" \
-H "x-api-key: {API_KEY}" \
-H "x-gw-ims-org-id: {IMS_ORG_ID}" \
-H "Authorization: Bearer {AUTHORIZATION_TOKEN}"\

{
    "result": "success"
}

Request example details

The example request above uses the DELETE method to remove the data view dv_650a049f5d02785bacxxxxxx.

Response example details

The example response above shows the DELETE was a success.

Request parameters

Response parameters

Connection Limits

The limits of dataviews per connection for the following products are:

• ARES_Only - 5
• Customery Journey Analytics Foundation Standalone - 500
• Customer Journey Analytics Select Standalone - 600
• Customer Journey Analytics Prime Standalone - 750
• Customer Journey Analytics Ultimate Standalone - 1000
• Customer Journey Analytics for Adobe Analtyics S/P/U - 600

API status codes

For a description of API status codes and tips for troubleshooting, see the Platform FAQ and troubleshooting guide.