The following document defines and provides samples for Data Subject Request API calls for the management of data within Kochava.
API Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| integer | ✔ | Numeric account ID for your Kochava account. Required for all requests. | |
| integer | Numeric app ID for the app to delete or access data from. Required for app-level requests. |
Request Body Parameters
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
| device_ids | ✔ | Array of objects containing the ID and its type. | | |
| Object containing necessary settings to notify clients using their preferred method. | |
Request Headers
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
| Authentication-Key | string | ✔ | Kochava API key to use for authentication | |
Delete Requests
Account Level Request:
Account level data to be scrubbed (deleted) from our data sources for the provided device identifiers across all apps associated to the api_key provided. An account_job_id will be
provided in the response which can be used to check the status of the job using the status endpoint.
Endpoint —
POST: https://nng.kochava.com/accounts/{accountID}/privacy/scrub
Headers —
Authentication-Key: API key
Request Body —
{
"device_ids": [
{
"id_type": "adid",
"id_value": "a_real_adid"
}
]
}
Response Body —
{
"status": "OK",
"response": "200",
"job_status": "queued",
"job_id": "job_id"
}App Level Request:
App level data to be deleted from our data sources for the provided device
Identifiers.
Endpoint —
POST: https://nng.kochava.com/accounts/{accountID}/apps/{appID}/privacy/scrub
Headers —
Authentication-Key: API key
Request Body —
{
"device_ids": [
{
"id_type": "adid",
"id_value": "a_real_adid"
}
]
}
Response Body —
{
"status": "OK",
"response": "200",
"job_status": "queued",
"job_id": "job_id"
}IdentityLink Request:
App level data to be deleted from our data sources for the provided IdentityLink.
Endpoint —
POST: https://nng.kochava.com/accounts/{accountID}/apps/{appID}/privacy/scrub
Headers —
Authentication-Key: API key
Request Body —
{ "device_ids": [
{
"id_type": "customer-idlink-name",
"id_value": "unique-customer-value"
}
]
}
Response Body —
{
"status": "OK",
"response": "200",
"job_status": "queued",
"job_id": "job_id"
}Access Requests
Account Request:
An access request will find any information associated to the given id(s) provided in the request that Kochava has stored across our systems. The most important part is the data_access_link property in the response. Once the job has completed a file will be generated and a link will be created that the client can click to download the data.
Endpoint —
POST: https://nng.kochava.com/accounts/{account_id}/apps/{app_id}/privacy/access
Headers —
Authentication-Key: API key
Content-Type: Application/JSON
Request Body —
{
"device_ids": [
{
"id_type": "<id_type>",
"id_value": "<id_value>"
}
]
}
Response Body —
{
"success": <true | false>,
"job_status": <pending|queued|failed|running|completed>,
"account_id": <account_id>,
"time_requested": <time_requested>,
"job_id": <job_id>,
"job_type": "access",
"app_id": <app_id>,
"data_access_link": <link to data>
}
App Request:
App level request to retrieve rows associated to the device identifiers provided.
Endpoint —
POST: http://nng.kochava.com/accounts/{accountID}/apps/{appID}/privacy/access
Headers —
Authentication-Key: API key
Request Body —
{
"device_ids": [
{
"id_type": "adid",
"id_value": "a_real_adid"
}
]
}
Response Body —
{
"status": "OK",
"response": "200",
"job_status": "queued",
"job_id": "job_id"
}Status Requests
Account Level Request:
Request the status of an entire account-level Delete or Access request. The
response includes a summary of the overall status of the account-level request
as well as a status of each of the app-level jobs that make up the
account-level request.
Placeholder Definitions —
| Placeholder | Definition |
|---|---|
| accountJobID | The job ID returned in the response of the initial account-level request. |
| job_type (access|scrub) | These are the possible values for `job_type` and indicate the type of request.
|
| job_id (appJobID) | The job ID unique to a account-level request’s sub-job. This can be used in an app-level Status request. |
| app_id (appID) | The numeric Kochava app ID the sub-job was processed for. |
| job_status | These are the possible values for the job’s status:
|
| rows_affected | These are the possible values for each data source:
|
Endpoint —
GET: https://nng.kochava.com/accounts/{accountID}/privacy/jobs/{accountJobID}/status
Headers —
Authentication-Key: API key
Response —
{
"success": {true | false},
"job_status": "{pending | queued | running | failed | completed}",
"account_id": {accountID},
"time_requested": "2022-10-24T16:07:09Z",
"job_id": "{accountJobID}",
"job_type": "{access | scrub}",
"account_jobs_requested": [
{
"job_id": "{appJobID}",
"app_id": {appID},
"status": "{queued | running | failed | completed}",
"time_started": "0001-01-01T00:00:00Z",
"rows_affected": {
"app_database": "{incomplete | failed | <rows affected> }",
"query_analytics": "{incomplete | failed | <rows affected> }",
"cold_storage": "{incomplete | failed | <rows affected> }"
}
},
...
]
}
App Level Request:
Endpoint —
POST: https://nng.kochava.com/accounts/{accountID}/apps/{appID}/privacy/jobs/{appJobID}/status
Headers —
Authentication-Key: API key
Response —
{
"success": {true | false},
"job_status": "{queued | running | failed | completed}",
"account_id": {accountID},
"time_requested": "2023-02-01T18:58:35Z",
"job_id": "{appJobID}",
"job_type": "{access | scrub}",
"app_id": {appID},
"time_finished": "2023-02-04T12:24:40Z",
"rows_affected": {
"app_database": "{incomplete | failed | <rows affected> }",
"query_analytics": "{incomplete | failed | <rows affected> }",
"cold_storage": "{incomplete | failed | <rows affected> }"
}
}
