Overview

Houseware application lets you export your cohorts created in Houseware to use outside the application also. This enables powerful use cases like personalization and targeted messaging for your users on top of these cohorts.

This documentation covers two primary APIs used to interact with cohort data. Both APIs require authentication and are designed to return specific details about cohorts and their generation queries.

Authentication

To access the APIs, you must include your API Key and SID with each request. These credentials must be included in the header of the HTTP request.

You can contact the Houseware team to get these credentials. They remain the same whenever you use the Houseware API.

API Endpoints

Get Cohorts

Retrieves a list of all cohorts along with their IDs, names, and descriptions. Try it out here!

• Endpoint: https://workbench-poc.houseware.io/api/v1/organization/product-analytics/api/cohorts

• Method: GET

• Headers:

  • houseware-api-key: Your unique API key.
  • houseware-sid: Your unique identifier

• Success Response:

  • Code: 200 OK

  • Content:

    • JSON

      \[  
        {  
          "cohort_uuid": "b53e443f-5a0e-400b-93b8-9a27fe8612306",  
          "name": "Active Users",  
          "description": "Users who have logged into the app in the last 28 days",  
          "definition": {  
            "type": "logical",  
            "values": \[  
              {  
                "type": "logical",  
                "values": \[  
                  {  
                    "type": "event",  
                    "action": "did",  
                    "date_range": {  
                      "type": "in_the_last",  
                      "window": {  
                        "unit": "day",
                        "value": 28  
                      },  
                      "end_date": "",  
                      "start_date": ""  
                    },  
                    "event_name": "Login",  
                    "aggregation": {  
                      "type": "count",  
                      "values": [  
                        1  
                      ],  
                      "operator": "gte"  
                    },  
          },  
          "organization_id": 1,  
          "created_by": 1,  
          "created_at": "2023-08-30T08:01:18.784242Z",  
          "updated_at": "2023-08-30T08:01:18.784242Z"  
        },
        ...
      
      ]
      

• Error Response:

  • Code: 401 Unauthorized
    Content: {"error": "Invalid API Key or SID"}

Get Cohort Query

Returns the SQL query required to generate a specific cohort. Try it out here!

• Endpoint: https://workbench-poc.houseware.io/api/v1/organization/product-analytics/api/cohorts/{cohort_uuid}/query
• Method: GET
• URL Parameters:
  • cohort_uuid: The unique identifier of the cohort.
• Headers:
  • houseware-api-key: Your unique API key.
  • houseware-sid: Your unique identifier
• Success Response:
  • Code: 200 OK
  • Content:

    • {
        "sql": "select * from table"
      }
      

• Error Response:
  • Code: 400 Bad Request
    Content: {"error": "Missing or invalid cohort_id"}
  • Code: 401 Unauthorized
    Content: {"error": "Invalid API Key or SID"}

Check out these APIs in action on the docs! If you're running into any trouble, reach out to the Houseware team on Slack or at [email protected]