Paulaschoice APIpaulaschoice.com ↗
Access Paula's Choice product data via 8 endpoints: search, details, INCI ingredients, allergen cautions, best sellers, and the ingredient dictionary.
What is the Paulaschoice API?
The Paula's Choice API exposes 8 endpoints covering product search, full product detail pages, INCI ingredient lists, allergen cautions, skin type and concern data, best sellers, paginated product listings, and a per-ingredient dictionary. The get_product_ingredients endpoint returns both the complete INCI string and a key ingredients spotlight with ratings and descriptions, while get_ingredient_info lets you look up any ingredient by name for its category, rating label, and related products.
curl -X GET 'https://api.parse.bot/scraper/a5c0a50b-a010-4b2d-a2e1-14ddf9c62511/get_product_detail?product_url=%2Fskin-perfecting-2pct-bha-liquid-exfoliant%2F201.html' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace paulaschoice-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Paula's Choice Skincare API - Usage Example
Discover products, explore ingredients, and get detailed skin compatibility info.
"""
from parse_apis.paula_s_choice_skincare_api import PaulasChoice, IngredientRating, IngredientNotFound
client = PaulasChoice()
# Search for retinol products — limit caps total items fetched
for product in client.products.search(query="retinol", limit=3):
print(product.name, product.rating, product.review_count)
# Get best sellers and drill into the first one's full details
top = client.products.best_sellers(limit=1).first()
if top:
detail = top.details()
print(detail.name, detail.rating, detail.skin_types)
# Check ingredients for the product
ingr = detail.ingredients()
for ki in ingr.key_ingredients:
print(ki.name, ki.categories, ki.rating)
# Check skin compatibility
skin = detail.skin_info()
print(skin.skin_types, skin.skin_concerns)
# Look up an ingredient in the dictionary — typed error on miss
try:
retinol = client.ingredients.get(ingredient_name="retinol")
print(retinol.name, retinol.rating)
except IngredientNotFound as exc:
print(f"Ingredient not found: {exc.ingredient_name}")
print("exercised: products.search / products.best_sellers / details / ingredients / skin_info / ingredients.get")
Fetch full product detail for a given product URL path. Returns structured product data including name, rating, review count, benefits, skin types/concerns, usage instructions, FAQ, awards, key ingredients spotlight, and available variants. The product URL path is the path portion after paulaschoice.com (e.g. '/skin-perfecting-2pct-bha-liquid-exfoliant/201.html').
| Param | Type | Description |
|---|---|---|
| product_urlrequired | string | Product URL path relative to paulaschoice.com (e.g. '/skin-perfecting-2pct-bha-liquid-exfoliant/201.html') |
{
"type": "object",
"fields": {
"id": "string product identifier",
"url": "string full product URL",
"name": "string product name",
"rating": "number rating score between 0 and 1",
"benefits": "array of benefit objects with text content",
"variants": "array of variant objects with id, name, size, price",
"how_to_use": "object with usage instructions including image and video",
"skin_types": "array of skin type strings",
"review_count": "integer number of reviews",
"skin_concerns": "array of skin concern strings"
},
"sample": {
"data": {
"id": "201",
"url": "https://www.paulaschoice.com/skin-perfecting-2pct-bha-liquid-exfoliant/201.html",
"name": "SKIN PERFECTING 2% BHA Liquid Exfoliant",
"rating": 0.84,
"benefits": [
{
"items": [
[
"Clears & minimizes enlarged pores"
]
],
"ordered": false
}
],
"variants": [
{
"id": "201-2010",
"sku": null,
"name": "2% BHA Liquid Exfoliant",
"size": "4 oz",
"price": null,
"available": null
}
],
"how_to_use": {
"image": {
"alt": "",
"url": "/on/demandware.static/-/Library-Sites-paulachoice/default/dwd171773e/images/pdp/how-to-use-image/how-to-use.gif"
},
"videoId": "q6BUHC8Xn6I"
},
"skin_types": [
"combination",
"oily",
"normal"
],
"review_count": 4956,
"skin_concerns": [
"breakouts",
"blackheads",
"dull"
]
},
"status": "success"
}
}About the Paulaschoice API
Product Data
The get_product_detail endpoint accepts a product URL path and returns a detailed record including name, rating (0–1 scale), review_count, benefits, skin_types, skin_concerns, how_to_use (with image and video references), and a variants array containing each variant's id, name, size, and price. The get_product_skin_info endpoint surfaces just the skin_types and skin_concerns arrays if you need a lightweight lookup without the full product record.
Ingredients and Allergens
get_product_ingredients returns two distinct fields: all_ingredients is the raw INCI list as a single string, and key_ingredients is an array of spotlight objects each with name, categories, description, rating, and keyPoints. Note that all_ingredients may be empty for some products if the INCI list is not available on the product page. The get_product_allergen_cautions endpoint extracts cautions from FAQ entries related to fragrance, sensitivity, and allergen warnings, and also returns an our_promise object covering the brand's non-irritating, cruelty-free, and guarantee statements.
Search and Listings
search_products accepts a keyword query and returns a products array with id, name, url, price, rating, review_count, description, image, and badge per product, plus a total_results count. list_all_products and get_best_sellers both support start and limit parameters for pagination and return a paging object with start, size, total, current page, and forward links alongside the product array.
Ingredient Dictionary
get_ingredient_info takes an ingredient_name (e.g., 'niacinamide', 'retinol', 'green-tea') and returns a structured record with a rating label ('Best', 'Good', 'Average', or 'Poor'), a categories array with category id, name, and url, a description array of paragraph objects, and a related_products array linking back to products that contain the ingredient.
The Paulaschoice API is a managed, monitored endpoint for paulaschoice.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when paulaschoice.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official paulaschoice.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build an ingredient safety checker by calling
get_product_ingredientsand cross-referencing INCI lists with a known allergen database. - Power a skincare recommendation engine using
skin_typesandskin_concernsfromget_product_skin_infoto match users to products. - Create a best-seller catalog widget using
get_best_sellerswith pagination to display top-ranked Paula's Choice products with prices and ratings. - Research ingredient quality tiers by querying
get_ingredient_infofor rating labels and category tags across a list of ingredient names. - Compare product formulations side-by-side by pulling
key_ingredientsspotlights fromget_product_ingredientsfor multiple product URLs. - Monitor fragrance-free and vegan product claims by parsing
cautionsandour_promisefields fromget_product_allergen_cautions. - Index the full Paula's Choice catalog for search by paginating
list_all_productswithstartandlimitand storing returnedid,name, andurlfields.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Paula's Choice have an official developer API?+
What does `get_ingredient_info` return, and how are ingredients identified?+
'retinol' or 'green-tea') and the endpoint returns a rating label (Best, Good, Average, or Poor), a categories array with each category's id, name, and url, a description array of paragraph-level text, and a related_products array. Ingredient names should match the slug format used in Paula's Choice Ingredient Dictionary URLs.Can the INCI ingredients list be empty?+
all_ingredients field in get_product_ingredients returns an empty string for some products when the full INCI list is not present on the product page. The key_ingredients spotlight array is typically populated even in those cases, so you can still retrieve highlighted ingredient data.Does the API cover Paula's Choice products sold on third-party retailers like Sephora or Amazon?+
Are customer review texts returned by any endpoint?+
get_product_detail and search endpoints expose aggregate rating scores and review_count integers. You can fork this API on Parse and revise it to add an endpoint that retrieves paginated review content for a product.