Data Retrieval & Insertion
Overview
This section explains how to access and insert data in Hushh, ensuring each operation aligns with user consent protocols. All endpoints in these categories require a valid session token (obtained via /sessiontoken) and, where applicable, a user’s phone number or ID.
1. Cards & Consents
1.1 List Installed Cards
Endpoint:
POST /api/v1/list-installed-cards
Description:
Retrieves all the “cards” (e.g., brand cards, preference cards) installed by a user.
Parameters:
phone_number
(query, string, required) — Identifies the user.token
(header, string, required) — Your valid session token.
Sample Request:
POST /api/v1/list-installed-cards?phone_number=+1234567890
Authorization: Bearer <token>
(Replace <token>
with the actual session token.)
Sample Response:
{
"status_code": 200,
"data": [
{
"brand_name": "Personal Information",
"category": "Demographic Card",
"id": 131
},
{
"brand_name": "Cuisine card",
"category": "Food - Personal",
"id": 60
},
{
"brand_name": "Travel Card",
"category": "Travel Preferences",
"id": 64
},
{
"brand_name": "Chanel",
"category": "Fashion, Dress, Personal",
"id": 15
},
{
"brand_name": "Insurance Card",
"category": "Insurance",
"id": 237
},
{
"brand_name": "Hushh ID card",
"category": "Hushh ID Card",
"id": 132
}
]
}
Field | Description |
---|---|
status_code | HTTP-like status code for the response |
data | Array of installed cards with name, category, and an internal ID |
Common Errors:
422 Validation Error
: Missing or invalidphone_number
parameter.Unauthorized
: Invalid or expired session token.
1.2 Request Consent
Endpoint:
POST /api/v1/request-consent
Description:
When a user’s consent is required for data access (e.g., brand preferences, health info), call this endpoint to prompt the user. The user is notified about the request with details of the developer and brand.
Request Body (JSON):
{
"phone_number": "string",
"access_token": "string",
"card_name": "string",
"expiry": "string"
}
Field | Type | Description |
---|---|---|
phone_number | string | User’s phone number for identification |
access_token | string | Additional token or identifier if needed (optional depending on flow) |
card_name | string | Name of the data scope (card) for which consent is requested |
expiry | string | Defines the timeframe or reason for which consent is being requested |
Sample Request:
POST /api/v1/request-consent
Content-Type: application/json
{
"phone_number": "+1234567890",
"access_token": "dev-access-12345",
"card_name": "Health Card",
"expiry": "3 days"
}
Possible Outcomes:
-
Immediate Accept/Reject (within 3 minutes):
- Response:
"Consent granted. You can access the data."
- or
"Consent rejected. You cannot access the data."
- Response:
-
No Response (user does not act within 3 minutes):
Response:
"Consent request sent and awaiting user acceptance. The request will remain valid for the next 24 hours. Please check again after 24 hours."
Common Errors:
422 Validation Error
: Invalid JSON structure or missing fields.Unauthorized
: Missing or invalid session token.User Already Granted/Replied
: If the user already granted or denied this specific consent, no further action is needed.
1.3 Get Consented Cards
Endpoint:
POST /api/v1/list-consented-cards
Description:
Retrieves a list of cards for which the user has already granted consent. This helps you identify which data scopes are accessible without further consent prompts.
Parameters:
phone_number
(query, string, required) — The user’s phone number.token
(header, string, required) — Your valid session token.
Sample Request:
POST /api/v1/list-consented-cards?phone_number=+1234567890
Authorization: Bearer <token>
(No request body required.)
Sample Response:
{
"status_code": 200,
"data": [
{
"card_id": 61,
"card_market": {
"brand_name": "Fashion card"
}
}
]
}
Field | Description |
---|---|
status_code | Indicates success/failure code (200 means successful retrieval). |
data | An array of consented cards, each with a card_id and metadata . |
card_market | Object containing card details like brand_name `. |
Common Errors
-
422 Validation Error
- Triggered if
phone_number
is missing or invalid. - Check that your request includes all required query parameters and proper formatting.
- Triggered if
-
401/403 Unauthorized/Forbidden
- Missing or invalid session token.
- Ensure you are sending
Authorization: Bearer <token>
with a valid token.
-
No Consents Found
- The user may not have consented to any cards yet, resulting in an empty
data
array.
- The user may not have consented to any cards yet, resulting in an empty
Usage Notes
- This endpoint complements List Installed Cards but specifically returns only those cards that the user has actively consented to share.
- Use this information to determine what data you can retrieve without sending another Request Consent call.
2. Receipts
2.1 Insert Receipt Data
Endpoint:
POST /api/v1/insert-receipt-data
Description: Upload receipt information—like brand, location, and total cost—to Hushh for a particular user.
Parameters:
phone_number
(query, string, required)token
(header, string, required)
Request Body (JSON):
{
"brand": "Dior",
"location": "New York, USA",
"purchase_category": "Electronics",
"brand_category": "Smartphones",
"Date": "2025-01-09T10:30:00Z",
"currency": "USD",
"payment_method": "Credit Card",
"total_cost": 999.99,
"inr_total_cost": 82500,
"usd_total_cost": 999.99
}
Field | Description |
---|---|
brand | Name of the brand (e.g., Dior, Apple, etc.) |
location | Where the purchase was made |
purchase_category | High-level category (Electronics, Groceries, etc.) |
brand_category | More specific subcategory (Smartphones, Laptops, etc.) |
Date | ISO8601 or date-time string indicating purchase date/time |
currency | Currency code (e.g., USD, INR) |
payment_method | Payment option (Credit Card, Cash, etc.) |
total_cost | Main transaction amount in the listed currency |
inr_total_cost | Conversion to INR (optional, if applicable) |
usd_total_cost | Conversion to USD (optional, if applicable) |
Sample Request:
POST /api/v1/request-consent
Content-Type: application/json
{
"brand": "Apple",
"location": "Online Store",
"purchase_category": "Electronics",
"brand_category": "Smartphones",
"Date": "2025-01-10T11:00:00Z",
"currency": "USD",
"payment_method": "Credit Card",
"total_cost": 1199.99,
"inr_total_cost": 99000,
"usd_total_cost": 1199.99
}
**Success Response(200 OK):**
```json
"Receipt data inserted successfully."
Field | Description |
---|---|
status_code | HTTP-like status code for the response |
data | Array of installed cards with name, category, and an internal ID |
Common Errors:
422 Validation Error
: Missing or invalid field.Forbidden
: No user consent if your application requires explicit approval for financial data.
### 1.1 Get Receipt User Data
**Endpoint:**
```bash
POST /api/v1/get-receipt-data
Description: Retrieves a list of previously stored receipts for the specified user.
Parameters:
phone_number
(query, string, required)token
(header, string, required)
Sample Request(HTTP):
POST /api/v1/health-data?phone_number=+1234567890
Authorization: Bearer <token>
Sample Response:
{
"status_code": 200,
"data": [
{
"answers": [
{
"answers": [
"{\"text\":\"Mental & Emotional Well-being\",\"image\":null}",
"{\"text\":\"Physical Health\",\"image\":null}"
],
"metadata": null,
"question": "What are your top health and wellness goals?",
"audio_url": null,
"questionType": "multiSelectQuestion"
},
{
"answers": [
"{\"text\":\"Dancing\",\"image\":null}",
"{\"text\":\"Strength Training\",\"image\":null}"
],
"metadata": null,
"question": "What types of exercise do you enjoy?",
"audio_url": null,
"questionType": "multiSelectQuestion"
},
{
"answers": [
"{\"text\":\"Vegetarian\",\"image\":null}"
],
"metadata": null,
"question": "Do you have any dietary restrictions or preferences?",
"audio_url": null,
"questionType": "multiSelectQuestion"
},
{
"answers": [
"{\"text\":\"Health Apps\",\"image\":null}"
],
"metadata": null,
"question": "What health apps or wearables do you use?",
"audio_url": null,
"questionType": "multiSelectQuestion"
}
]
}
]
}
Field | Description |
---|---|
status_code | Indicates success/failure code |
data | Array of objects, each containing answers and question info |
Common Errors:
422 Validation Error
: Missing or phone_number.Forbidden
: User consent not granted for health data.Empty Data
: User has not yet stored any health information.
Health
3.1 Insert Health Data
Endpoint:
POST /api/v1/insert-health-data
Description: Allows your application to store user health-related information. This can be custom survey data, fitness metrics, or any health-related answers keyed under answers.
Parameters:
phone_number
(query, string, required)token
(header, string, required)
Request Body (JSON):
{
"answers": [
{
"question": "What are your top health and wellness goals?",
"answers": [
"{\"text\":\"Mental & Emotional Well-being\"}",
"{\"text\":\"Physical Health\"}"
]
}
]
}
Request Request (HTTP):
POST /api/v1/insert-health-data?phone_number=+1234567890
Authorization: Bearer <token>
Content-Type: application/json
{
"answers": [
{
"question": "What are your top health and wellness goals?",
"answers": [
"{\"text\":\"Mental & Emotional Well-being\"}",
"{\"text\":\"Physical Health\"}"
]
}
]
}
Success Response(200 OK):
"Health data inserted successfully."
Common Errors:
422 Validation Error
: Missing phone_number or malformed request body.Forbidden
: User has not granted consent for health data access/updates.
3.1 Get Health Data
Endpoint:
POST /api/v1/api/v1/health-data
Description: Retrieves the user’s stored health data, which often includes question-and-answer survey responses or other custom health metrics.
Parameters:
phone_number
(query, string, required)token
(header, string, required)
Sample Request(HTTP)
POST /api/v1/health-data?phone_number=+1234567890
Authorization: Bearer <token>
Success Response:
{
"status_code": 200,
"data": [
{
"answers": [
{
"answers": [
"{\"text\":\"Mental & Emotional Well-being\",\"image\":null}",
"{\"text\":\"Physical Health\",\"image\":null}"
],
"metadata": null,
"question": "What are your top health and wellness goals?",
"audio_url": null,
"questionType": "multiSelectQuestion"
},
{
"answers": [
"{\"text\":\"Dancing\",\"image\":null}",
"{\"text\":\"Strength Training\",\"image\":null}"
],
"metadata": null,
"question": "What types of exercise do you enjoy?",
"audio_url": null,
"questionType": "multiSelectQuestion"
},
{
"answers": [
"{\"text\":\"Vegetarian\",\"image\":null}"
],
"metadata": null,
"question": "Do you have any dietary restrictions or preferences?",
"audio_url": null,
"questionType": "multiSelectQuestion"
},
{
"answers": [
"{\"text\":\"Health Apps\",\"image\":null}"
],
"metadata": null,
"question": "What health apps or wearables do you use?",
"audio_url": null,
"questionType": "multiSelectQuestion"
}
]
}
]
}
Field | Description |
---|---|
status_code | Indicates success/failure code |
data | Array of objects, each containing answers and question info |
Common Errors:
422 Validation Error
: Missing or invalid phone_number.Forbidden
: User consent not granted for health data.Empty Data
: User has not yet stored any health information.
Browsing
4.1 Insert Browsing Data
Endpoint:
POST /api/v1/insert-browsing-data
Description: Captures user browsing information, such as visited URLs, click counts, and interest keywords.
Parameters:
phone_number
(query, string, required)token
(header, string, required)
Request Body (JSON):
{
"website_url": "https://example.com/product-page",
"visit_time": "2025-01-09T12:00:00Z",
"product_clicks": 5,
"interest_keywords": "smartphones, electronics, gadgets",
"brand": "Samsung",
"source": "Google Search",
"duration": 120
}
Field | Description |
---|---|
website_url | The URL the user visited |
visit_time | Date/time of visit (ISO8601) |
product_clicks | Number of product pages or items clicked |
interest_keywords | Comma-separated string of interest keywords |
brand | Brand or product manufacturer associated with visit |
source | Source of referral (e.g., Google, direct link) |
duration | Time spent in seconds on the page |
Success Response(200 OK):
"Browsing data inserted successfully."
Common Errors:
422 Validation Error
: Missing or invalid field.Forbidden
: Consent issues if user hasn’t allowed browsing data sharing.
4.1 Get Browsing Data
Endpoint:
POST /api/v1/browsing-data
Description: Retrieves previously inserted browsing records for a user, enabling analytics or personalized recommendations.
Parameters:
phone_number
(query, string, required)token
(header, string, required)
Sample Request(HTTP)
POST /api/v1/browsing-data?phone_number=+1234567890
Authorization: Bearer <token>
Success Response:
{
"status_code": 200,
"data": [
{
"visit_time": "2025-01-09T18:37:30+00:00",
"website_url": "amazon.in",
"product_clicks": 23,
"interest_keywords": [
{
"Interest Keywords": "Heels"
}
],
"brand": "Monrow",
"source": "Amazon",
"duration": 45
}
]
}
Field | Description |
---|---|
visit_time | Timestamp of when the user browsed |
website_url | The domain or page visited |
product_clicks | Number of product pages clicked in that session |
interest_keywords | Potentially an array or structure of user interests |
brand | Associated brand for this browsing session |
source | Where the traffic originated (e.g., Amazon, Google, etc.) |
duration | Number of seconds spent on the site |
Common Errors:
422 Validation Error
: Invalid or missing parameters.Forbidden
: Lack of user consent for browsing data retrieval.
Brand Preferences
5.1 Insert Brand Preference Data
Endpoint:
POST /api/v1/insert-brand-preference-data
Description: Stores user responses related to a particular brand—e.g., preferences, wishlists, or survey answers.
Parameters:
phone_number
(query, string, required)brand_name
(query, string, required)token
(header, string, required)
Request Body (JSON) Example:
{
"answers": [
{
"question": "Which Dior product categories do you prefer?",
"answers": [
"{\"text\":\"Handbags\"}",
"{\"text\":\"Beauty\"}"
]
}
]
}
Success Response(200 OK):
"Brand preference data inserted successfully."
Common Errors:
422 Validation Error
: Missing or invalid field.Forbidden
: If user has not consented to share brand preference data.
Get Brand Preference
Endpoint:
POST /api/v1/brand-preferences
Description: Retrieves any brand-specific preferences the user has previously shared (e.g., product categories, style choices).
Parameters:
phone_number
(query, string, required)brand_name
(query, string, required)token
(header, string, required)
Sample Request(HTTP)
POST /api/v1/brand-preferences?phone_number=+1234567890&brand_name=Dior
Authorization: Bearer <token>
Success Response:
{
"status_code": 200,
"data": [
{
"answers": [
{
"answers": [
"{\"text\":\"Lady Dior\",\"image\":null}"
],
"metadata": null,
"question": "What bag styles from Dior do you own or aspire to own?",
"audio_url": null,
"questionType": "multiSelectQuestion"
},
{
"answers": [
"{\"text\":\"Handbags\",\"image\":null}",
"{\"text\":\"Beauty\",\"image\":null}"
],
"metadata": null,
"question": "Which Dior product categories do you prefer?",
"audio_url": null,
"questionType": "multiSelectQuestion"
},
{
"answers": [
"{\"text\":\"Neutral\",\"image\":null}"
],
"metadata": null,
"question": "How important is staying up to date with Dior's seasonal runway shows and collections?",
"audio_url": null,
"questionType": "multiSelectQuestion"
}
]
}
]
}
Field | Description |
---|---|
status_code | Indicates success/failure code |
data | Array of preference objects with question-and-answer details |
Common Errors:
422 Validation Error
: Missing phone_number or brand_name.Forbidden
: User has not consented to share brand preference data or brand name is invalid.
Fashion
Insert Fashion Data
Endpoint:
POST /api/v1/insert-fashion-data
Description: Captures user fashion-related details, such as style preferences, favorite designers, or questionnaire responses.
Parameters:
phone_number
(query, string, required)token
(header, string, required)
Request Body (JSON) Example:
{
"answers": [
{
"question": "Which brands do you follow for the latest fashion trends?",
"answers": [
"{\"text\":\"Gucci\"}",
"{\"text\":\"Prada\"}"
]
},
{
"question": "Preferred styles?",
"answers": [
"{\"text\":\"Streetwear\"}",
"{\"text\":\"Formal\"}"
]
}
]
}
Field | Description |
---|---|
answers | Array of Q&A objects related to user fashion. Structure can be tailored per your needs. |
Sample Request (HTTP):
POST /api/v1/insert-fashion-data?phone_number=+1234567890
Authorization: Bearer <token>
Content-Type: application/json
{
"answers": [
{
"question": "Which brands do you follow for the latest fashion trends?",
"answers": [
"{\"text\":\"Gucci\"}",
"{\"text\":\"Prada\"}"
]
},
{
"question": "Preferred styles?",
"answers": [
"{\"text\":\"Streetwear\"}",
"{\"text\":\"Formal\"}"
]
}
]
}
Success Response (200 OK):
"Fashion data inserted successfully."
Common Errors:
422 Validation Error
: Missing parameters or invalid JSON structure.Forbidden
: The user has not consented to share fashion data.
Get Fashion Data
Endpoint:
POST /api/v1/fashion-data
Description: Retrieves previously inserted fashion preferences and Q&A responses for a given user.
Parameters:
phone_number
(query, string, required)token
(header, string, required)
Sample Request (HTTP):
POST /api/v1/insert-fashion-data?phone_number=+1234567890
Authorization: Bearer <token>
Content-Type: application/json
Sample Response (Example):
{
"status_code": 200,
"data": [
{
"answers": [
{
"question": "Which brands do you follow for the latest fashion trends?",
"answers": [
"{\"text\":\"Gucci\"}",
"{\"text\":\"Prada\"}"
]
},
{
"question": "Preferred styles?",
"answers": [
"{\"text\":\"Streetwear\"}",
"{\"text\":\"Formal\"}"
]
}
]
}
]
}
Field | Description |
---|---|
status_code | Custom success/failure code. |
data | Array of objects that include user’s fashion Q&A responses or metadata. |
Common Errors:
422 Validation Error
: Missing phone_number or other required parameters.Forbidden
: User has not granted consent for fashion data retrieval.
Food
Get Food Data
Endpoint:
POST /api/v1/food-data
Description: Retrieves any stored food-related information for the user, which may include dietary preferences, favorite cuisines, or past food survey responses.
Parameters:
phone_number
(query, string, required)token
(header, string, required)
Sample Request (HTTP):
POST /api/v1/food-data?phone_number=+1234567890
Authorization: Bearer <token>
Sample Response (Example):
{
"status_code": 200,
"data": [
{
"dietary_preferences": [
"Vegetarian",
"Gluten-Free"
],
"favorite_cuisines": [
"Italian",
"Mexican"
]
}
]
}
(The exact structure may vary based on how you insert or query food data.)
Common Errors:
422 Validation Error
: Missing or invalid parameters.Forbidden
: The user has not consented to share food-related data.Empty Data
: No food data found for this user.
Insurance
Get Insurance Data
Endpoint:
POST /api/v1/insurance-data
Description: Retrieves insurance-related information for the user, such as policy details, coverage limits, or any survey answers about insurance preferences.
Parameters:
phone_number
(query, string, required)token
(header, string, required)
Sample Request (HTTP):
POST /api/v1/insurance-data?phone_number=+1234567890
Authorization: Bearer <token>
Sample Response (Example):
{
"status_code": 200,
"data": [
{
"policy_type": "Health Insurance",
"policy_provider": "Global Health Co.",
"coverage_amount": 50000,
"policy_expiry_date": "2025-12-31",
"premium_due": 1200
}
]
}
Field | Description |
---|---|
policy_type | e.g., Health, Life, Travel |
policy_provider | Name of the insurance company |
coverage_amount | Coverage limit or sum assured |
policy_expiry_date | Date (YYYY-MM-DD) or timestamp indicating when policy expires |
premium_due | Cost in the specified currency (USD, etc.) |
Common Errors:
422 Validation Error
: Missing phone_number.Forbidden
: User has not consented to share insurance data.Not Found
: User has no insurance info stored.
Insurance
Beyond basic endpoint usage, there are a few critical aspects to keep in mind when working with Hushh Developer APIs. These considerations help ensure that your integrations remain seamless, secure, and fully compliant with global data protection standards.
Consent Flow
Overview
Hushh places user consent at the heart of data sharing. Even if a user’s data exists in Hushh, your application must explicitly request user permission to access it. This ensures privacy, transparency, and compliance with regulations like GDPR.
Workflow Steps
-
Attempt Data Retrieval
- If consent has already been granted, the API will return the requested data.
- If consent is missing, you receive a message:
“You don’t have permission to access the data. Please request consent from the user.”
-
Request Consent
- Call the
POST /api/v1/request-consent
endpoint to prompt the user. - The user sees your application’s details (developer info, brand name, etc.) and decides whether to accept or reject.
- Call the
-
Immediate 3-Minute Window
- Hushh keeps the request open for 3 minutes for a potential instant response:
- Consent Granted: You can immediately access the data.
- Consent Rejected: You cannot access the data.
- Hushh keeps the request open for 3 minutes for a potential instant response:
-
24-Hour Pending
- If the user does not act within the 3-minute window, the request remains pending for 24 hours.
- Your application will receive a message:
“Consent request sent and awaiting user acceptance. Please check again after 24 hours.”
-
Check Status
- After 24 hours (or anytime in between), you can check if the user finally responded.
- Once consent is granted, your subsequent data retrieval calls should succeed.
Best Practices
- Request Consent Only When Needed: Avoid overwhelming the user with multiple consent prompts.
- Provide Context: In your UI or notifications, clarify why the data is needed and how it benefits the user.
- Handle Pending Status Gracefully: If consent is pending, inform the user that data will be available once they respond to the request.