PerfectFitAPI v1
← HomeStore demo

API documentation

API v1REST · JSON · Bearer token

Integrate the PerfectFit size recommendation engine on your site in a few lines.

Authentication

Every request must include your API key in the Authorization :

Authorization: Bearer pf_live_...
pf_live_… · server key

For your back-end calls (server to server). Full API access. Keep it secret — never expose it in the browser.

pf_pub_… · widget key

For the client-side widget. Read + recommendation only, locked to your domains (origin-lock). Safe to expose in the browser. Generated from the admin.

Active key for testing
Active key: pf_live_YOUR_KEY_HERE
Base URL
https://perfect-fit-poc.vercel.app/api/v1
💡
No-code integration available

Prefer the widget script tag if you don't have a backend. A single <script> tag is enough.

Endpoints
JavaScript integration example
// 1. Get a size recommendation
const response = await fetch('https://perfect-fit-poc.vercel.app/api/v1/recommend', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer pf_live_YOUR_KEY_HERE',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    chest_cm: 96,
    waist_cm: 80,
    category: 'tshirt',
    gender: 'homme',
  }),
});

const { recommended_size, score } = await response.json();
// → { recommended_size: "M", score: 91, label: "Great fit" }

// 2. Fetch the products available in size M
const products = await fetch(
  'https://perfect-fit-poc.vercel.app/api/v1/products?size=' + recommended_size + '&category=tshirt',
  { headers: { 'Authorization': 'Bearer pf_live_YOUR_KEY_HERE' } }
).then(r => r.json());
Widget integration (no-code)

The PerfectFit widget integrates with a single <script> tag on your product page. It shows a floating "Find my size" button that opens a modal iframe — no build, no dependency.

Try it on the interactive demo →

Installation snippet
<script
  src="https://perfect-fit-poc.vercel.app/widget.js"
  data-pf-key="pf_live_YOUR_KEY_HERE"
  data-pf-tenant="celio-fr"
  data-pf-category="tshirt"
  data-pf-gender="homme"
  data-pf-color="#E30613"
  data-pf-label="Find my size"
  data-pf-position="bottom-right"
  async>
</script>
Available attributes
AttributeRequiredDefaultDescription
data-pf-keyYes—Public tenant API key (format pk_live_…)
data-pf-tenantYes—Tenant slug (e.g. celio-fr). Used to load the color/logo config.
data-pf-categoryNo""Pre-selected category: tshirt · pantalon · pull · manteau
data-pf-genderNo""Pre-selected gender: homme · femme
data-pf-colorNoTenant configAccent color of the button and iframe (hex). Overrides the tenant config.
data-pf-labelNoFind my sizeFloating button text.
data-pf-positionNobottom-rightButton position: bottom-right · bottom-left · top-right · top-left
data-pf-product-idNo""Product ID to pre-fill the recommendation context.
postMessage API

The widget exposes window.PerfectFit for programmatic control:

// Open / close manually
window.PerfectFit.open();
window.PerfectFit.close();

// Listen for the recommendation from the iframe
window.addEventListener('message', function(e) {
  if (e.data && e.data.type === 'PF_RECOMMENDATION') {
    console.log('Recommended size:', e.data.size);  // "M"
    console.log('Score:', e.data.score); // 91
  }
});

The iframe sends PF_CLOSE to request closing, and PF_RECOMMENDATION on a successful recommendation.

PerfectFit API v1 · Contact: api@perfect-fit.io