AI-Powered Hair Product Recommendations via the API
Send a hair profile to the Black Hair API and receive ranked product picks with plain-English explanations matched to hair type, porosity, and concerns.
The recommendation endpoint matches products to a specific hair profile and returns each suggestion with a plain-English explanation of why it suits the user’s exact hair type, porosity, and concerns. Rather than relying on keyword matching alone, the API analyses the full hair profile semantically, finds the most relevant product candidates, and then ranks and explains each one in natural language.
The /v1/recommend/ endpoint requires a Pro or Enterprise plan. Requests made with a Starter or Growth API key receive a 403 Forbidden response. See Plans and Limits for details.
Your request body describes the user’s hair characteristics: hair_type, porosity, concerns, budget_max, and any exclude_ingredients. The API uses these to understand the full picture of the user’s hair needs.
2
Find the most relevant products
The API identifies the products in the catalog that best match the supplied hair profile, drawing on hair type compatibility, porosity suitability, and ingredient composition.
3
Filter by budget and excluded ingredients
Candidates are filtered: any product whose minimum price exceeds budget_max, or whose ingredient list contains an entry from exclude_ingredients, is removed before ranking.
4
Rank and explain each result
The remaining candidates are ranked by relevance. Each recommendation comes with a 2–3 sentence explanation written specifically for the supplied hair profile, so your users understand exactly why each product was chosen for them.
Hair porosity level: "low", "medium", or "high". Porosity determines how well hair absorbs and retains moisture and is the single most influential factor in ranking.
A list of hair concerns to address. Common values: "dryness", "breakage", "frizz", "scalp health", "shrinkage", "split ends". Defaults to an empty list.
The maximum product price the user is willing to pay, in the specified currency. Products whose minimum price exceeds this value are excluded before ranking.
Ingredient names to exclude. Products whose full ingredient list contains any of these strings (case-insensitive) are removed before ranking. Defaults to an empty list.
The maximum number of recommendations to return. Defaults to 5. The final count may be lower than limit if many candidates are filtered out by budget or ingredient exclusions.
A successful response contains the echoed query object and a recommendations array sorted by rank.Example response
{ "query": { "hair_type": "4c", "porosity": "high", "concerns": ["dryness", "breakage"] }, "recommendations": [ { "rank": 1, "reason": "This deep conditioner is specifically formulated for high-porosity 4C hair. Its shea butter and castor oil base delivers the heavy moisture 4C coils need to combat dryness, while the protein-free formula avoids the stiffness that can lead to breakage on already brittle strands.", "product": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Honey & Shea Deep Conditioner", "brand": "Mielle Organics", "category": "deep-conditioner", "price_range": { "min": 9.99, "max": 12.99, "currency": "GBP" }, "buy_url": "https://www.mielleorganics.com/products/honey-shea-deep-conditioner", "hair_types": ["4b", "4c"], "sulphate_free": true, "silicone_free": true } }, { "rank": 2, "reason": "Formulated with penetrating oils like avocado and olive, this leave-in conditioner is an excellent match for high-porosity hair that loses moisture quickly. The lightweight consistency coats each strand without weighing down 4C coils, and its slip aids in detangling, reducing the mechanical stress that causes breakage.", "product": { "id": "c3d4e5f6-a7b8-9012-cdef-234567890abc", "name": "Avocado Hydration Leave-In", "brand": "Camille Rose", "category": "leave-in", "price_range": { "min": 11.99, "max": 14.99, "currency": "GBP" }, "buy_url": "https://www.camillerose.com/products/avocado-hydration-leave-in", "hair_types": ["3c", "4a", "4b", "4c"], "sulphate_free": true, "silicone_free": true } } ]}
Be specific about porosity. Porosity is the primary signal used during ranking. Passing "high" instead of leaving it vague significantly improves result relevance, because high-porosity hair needs heavier, sealing products while low-porosity hair benefits from lighter, heat-activated formulas.
List your actual concerns. The more specific your concerns array, the more targeted the explanations will be. Use precise terms like "dryness", "frizz", "breakage", "scalp health", "shrinkage", or "split ends" rather than general descriptors.
Set a realistic budget_max. Budget filtering happens before ranking, so an overly restrictive budget reduces the candidate pool and may result in fewer than limit recommendations being returned. If you get fewer results than expected, try raising budget_max or removing it entirely.
For a full list of accepted hair_type and porosity values, see Hair Profiles. For rate limits and plan quotas, see Plans and Limits.
