--- title: Data API description: Access your data through our API. ---
Reach out to us at support@churnkey.co to speak about getting API access for your company.
:: ## Authorization Authorization is done with your data API key, which is distinct from the Cancel Flow API key. Once you have your key, you will pass it along with your application ID as request headers. You can find your API keys and App ID on [Churnkey | Settings | Account](https://app.churnkey.co/settings/account). ```jsx HEADERS { "x-ck-api-key": "data_your_key...", "x-ck-app": "appIdHere", "content-type": "application/json" } ``` ## List Sessions This endpoint will return an array of sessions, optionally filtered. This is limited to returning 10,000 sessions per request. ```jsx GET "https://api.churnkey.co/v1/data/sessions" HEADERS { "x-ck-api-key": "data_your_key...", "x-ck-app": "appIdHere", "content-type": "application/json" } ``` Optionally, you can include the following filters as query params. | **Filter** | **Example** | **Description** | | ----------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `limit` | `10` | Maximum number of sessions to return (default: 100, max: 10,000) | | `skip` | `10` | Number of sessions to skip for manual pagination. Use with `limit` for paginated results. | | `startDate` | `2023-01-01` | Sessions that occurred after this date according to `new Date(startDate)` | | `endDate` | `2024-01-01` | Sessions that occurred before this date according to `new Date(endDate)` | | `customerId` | `cus_123789` | The exact customer ID. | | `trial` | `true` | If customer was on a subscription trial at the time of session | | `billingInterval` | `MONTH` | Customer subscription billing interval. Possible values are `WEEK`, `MONTH`, `YEAR` | | `planId` | `billing_plan_id` | The exact billing plan ID. | | `aborted` | `true` | If session was abandoned before completion | | `canceled` | `true` | If customer canceled their subscription | | `offerType` | `PAUSE` | Type of accepted offer if accepted. Possible values are `PAUSE`, `DISCOUNT`, `CONTACT`, `PLAN_CHANGE`, `REDIRECT`, `TRIAL_EXTENSION` | | `saveType` | `ABANDON` | Type of accepted offer if accepted, or `ABANDON` if session was abandoned before completion. Possible values are `PAUSE`, `DISCOUNT`, `CONTACT`, `PLAN_CHANGE`, `REDIRECT`, `TRIAL_EXTENSION`, `ABANDON` | | `couponId` | `coupon_abc12` | The ID of the coupon if the customer accepted a discount offer. | | `pauseDuration` | `2` | How long the customer paused their subscription for if they accepted a pause offer. | | `blueprintId` | `id-goes-here-7890` | ID of the version of the published Cancel Flow. | | `abtest` | `guid-goes-here-7890` | ID of an ongoing or completed AB test. | | `bounced` | `true` | By default, `bounced` is set to `false` and bounced sessions are excluded (see note below). | ::alert{type="warning" emoji="💡"} A session gets marked as bounced if another more relevant session takes place within 24 hours of that initial session. For instance, if a customer pauses and then decides to cancel within 24 hours, that first session with the pause offer accepted will be marked as bounced. :: ### Examples of List Session Requests 1. Returns sessions for the month of May 2023 `GET "https://api.churnkey.co/v1/data/sessions?startDate=2023-05-01&endDate=2023-06-01"` 2. Returns sessions where monthly customers accepted a discount `GET "https://api.churnkey.co/v1/data/sessions?offerType=DISCOUNT&billingInterval=MONTH"` ### Manual Pagination Examples Use `limit` and `skip` parameters together to implement manual pagination: 1. **First page** - Get the first 10 sessions: `GET "https://api.churnkey.co/v1/data/sessions?limit=10"` 2. **Second page** - Get sessions 11-20: `GET "https://api.churnkey.co/v1/data/sessions?limit=10&skip=10"` 3. **Third page** - Get sessions 21-30: `GET "https://api.churnkey.co/v1/data/sessions?limit=10&skip=20"` ### Response Data Format ```jsx [ { _id: '63fffe3...', org: '5fc5c5483b...', blueprintId: '63ce7c2152...', segmentId: '63ce7be8d0d...', abtest: '63ce7c35e...', customer: { id: 'cus_123', email: 'janedoe@gmail.com', created: '2022-12-24T03:24:59.000Z', subscriptionId: 'sub_1M...', subscriptionStart: '2022-12-24T03:25:09.000Z', subscriptionPeriodStart: '2023-02-24T03:25:09.000Z', subscriptionPeriodEnd: '2023-03-24T03:25:09.000Z', currency: 'usd', planId: 'creator_monthly', planPrice: 1299, itemQuantity: 1, billingInterval: 'MONTH', billingIntervalCount: 1, }, acceptedOffer: { guid: 'dba-ea0be-a20f-...', offerType: 'PAUSE', pauseInterval: 'MONTH', pauseDuration: 3, }, provider: 'STRIPE', aborted: false, canceled: false, surveyId: '929f...', surveyChoiceId: 'e32f1...', surveyChoiceValue: 'Missing Features', feedback: 'I want to be able to add animations to the video', discountCooldownApplied: false, customActionHandler: null, presentedOffers: [ { guid: '1c85...', accepted: false, presentedAt: '2023-03-02T01:38:28.039Z', declinedAt: '2023-03-02T01:38:35.462Z', surveyOffer: false, offerType: 'PAUSE', pauseConfig: { maxPauseLength: 2, pauseInterval: 'MONTH', }, }, { guid: 'dba...', accepted: true, presentedAt: '2023-03-02T01:38:41.931Z', acceptedAt: '2023-03-02T01:38:55.903Z', surveyOffer: true, offerType: 'DISCOUNT', discountConfig: { couponId: 'coup_id', }, }, ], mode: 'LIVE', createdAt: '2023-03-02T01:38:56.005Z', updatedAt: '2023-03-02T01:38:56.684Z', recordingEndTime: '2023-03-02T01:38:56.032Z', recordingStartTime: '2023-03-02T01:38:27.276Z', }, ]; ``` ## Aggregated Session Data This endpoint will return an array of grouped session counts. Like the above session listing endpoint, this data can be filtered. Additionally, it can be aggregated by nested groups. ```jsx GET "https://api.churnkey.co/v1/data/session-aggregation" HEADERS { "x-ck-api-key": "data_your_key...", "x-ck-app": "appIdHere", "content-type": "application/json" } ``` In addition to the above filters, you can group the session aggregation by adding any of the following to the `breakdown` query param, separating each with a `-` e.g. `?breakdown=month-saveType` | **Filter** | **Description** | | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `month` | Which month the session occurred in. | | `trial` | If customer was on a subscription trial at the time of session | | `billingInterval` | Customer subscription billing interval. Possible values are `WEEK`, `MONTH`, `YEAR` | | `planId` | The exact billing plan ID. | | `aborted` | If session was abandoned before completion | | `canceled` | If customer canceled their subscription | | `offerType` | Type of accepted offer if accepted. Possible values are `PAUSE`, `DISCOUNT`, `CONTACT`, `PLAN_CHANGE`, `REDIRECT`, `TRIAL_EXTENSION` | | `saveType` | Type of accepted offer if accepted, or `ABANDON` if session was abandoned before completion. Possible values are `PAUSE`, `DISCOUNT`, `CONTACT`, `PLAN_CHANGE`, `REDIRECT`, `TRIAL_EXTENSION`, `ABANDON` | | `couponId` | The ID of the coupon if the customer accepted a discount offer. | | `pauseDuration` | How long the customer paused their subscription for if they accepted a pause offer. | | `blueprintId` | ID of the version of the published Cancel Flow. | | `abtest` | ID of an ongoing or completed AB test. | ### Examples of Aggregate Session Requests 1. A month-by-month breakdown of the different types of offers accepted since the start of 2023 `GET "https://api.churnkey.co/v1/data/session-aggregation?startDate=2023-01-01&breakdown=month-offerType"` 2. A month-by-month breakdown of the survey responses for monthly vs annual customers `GET "https://api.churnkey.co/v1/data/session-aggregation?startDate=2023-01-01&breakdown=month-surveyResponse-billingInterval"` ### Response Data Format ```jsx [ { "count": 70, "month": "2023-02", "surveyResponse": "Doesn't Fit My Budget", "billingInterval": "MONTH" }, { "count": 4, "month": "2023-03", "surveyResponse": "Missing Features", "billingInterval": "MONTH" }, { "count": 4, "month": "2023-01", "surveyResponse": "Technical Issues", "billingInterval": "MONTH" }, { "count": 12, "month": "2023-01", "surveyResponse": "Stopped Creating", "billingInterval": "YEAR" }, { "count": 5, "month": "2023-01", "surveyResponse": "Missing Features", "billingInterval": "MONTH" }, ... ] ``` ## GDPR User Data Access For data service requests for access ```jsx POST "https://api.churnkey.co/v1/data/dsr/access" BODY { "email": "jane@example.com" } HEADERS { "x-ck-api-key": "data_your_key...", "x-ck-app": "appIdHere", "content-type": "application/json" } ``` ### Response Data Format ```jsx { "customer": { "email": "jane@example.com" }, "counts": { "events": 5, "sessions": 5, "campaigns": 5, "invoices": 10, "failedPayments": 5, "subscriptions": 5, "charges": 5, "emails": 0 }, "profile": { "events": [...], "sessions": [...] "invoices": [...], "campaigns": [...], "failedPayments": [...], "subscriptions": [...], "charges": [...], "emails": [...] } } ``` ## GDPR User Data Delete Request For data service requests for access ```jsx POST "https://api.churnkey.co/v1/data/dsr/delete" BODY { "email": "jane@example.com" } HEADERS { "x-ck-api-key": "data_your_key...", "x-ck-app": "appIdHere", "content-type": "application/json" } ``` ### Successful Response Data Format ```jsx { "customer": { "email": "jane@example.com" }, "deleted": true, "deletedCounts": { "events": 0, "sessions": 0, "campaigns": 0, "invoices": 0, "failedPayments": 0, "subscriptions": 0, "charges": 0, "emails": 0 }, "counts": { "events": 0, "sessions": 0, "campaigns": 0, "invoices": 0, "failedPayments": 0, "subscriptions": 0, "charges": 0, "emails": 0 } } ``` ### Rejected Response Data Format ```jsx { "customer": { "email": "jane@example.com" }, "deleted": false, "reasonForRejection": "Profile exceeds limit for API deletion. Please contact support@churnkey.co.", "counts": { "events": 50000, "sessions": 0, "campaigns": 0, "invoices": 0, "failedPayments": 0, "subscriptions": 0, "charges": 0, "emails": 0 } } ```