# Engagement ring configurator API

ShowroomPro gives developers and AI agents an engagement ring configurator they can add with an API call instead of building one. The configurator itself (quiz, AI rendering, lead capture) is hosted. Your code creates it, embeds it and receives what it produces.

| Step | Endpoint | Auth |
| --- | --- | --- |
| Create a configurator | `POST /api/v1/sandboxes` | None |
| Embed it | `embed.js` snippet from the response | None (public token) |
| Check install and claim | `GET /api/v1/sandboxes/status/{token}` | None |
| Receive leads and designs | Webhooks: `lead.created`, `design.generated`, `quote.requested` | HMAC-SHA256 signature |
| Read a full session | `GET /api/webhooks/sessions/{id}` | Bearer webhook secret |

Machine-readable: [OpenAPI 3.1 spec](https://www.showroompro.ai/openapi.json).

## Create one

```bash
curl -s -X POST https://www.showroompro.ai/api/v1/sandboxes \
  -H "Content-Type: application/json" \
  -d '{"businessName":"Atelier Rose Jewelers","platform":"custom","source":"my-app"}'
```

The response contains the embed snippets, a public quiz URL and a private claim URL for the jeweler. Details: [Sandbox & claim API](https://www.showroompro.ai/docs/sandbox-api.md).

## Embed it

```html
<div data-showroompro-ring-builder="YOUR_TOKEN"></div>
<script src="https://www.showroompro.ai/embed.js" async></script>
```

Control it from your page with `ShowroomPro.open()`, `ShowroomPro.on("design_generated", fn)` and the other [JavaScript API methods](https://www.showroompro.ai/docs/widget.md#javascript-api-and-events).

## Receive the results

After the jeweler claims the configurator, webhooks deliver each lead and design as JSON, including stone type, shape, carat, setting, metal, band, budget, ring size, timeline and image URLs. Verify the `X-RingBuilder-Signature` header with your secret. See [Webhooks](https://www.showroompro.ai/docs/webhooks.md).

## Questions

### Can I render a ring image from my own UI through the API?

Not today. Rendering happens inside the hosted quiz so shopper limits, consent and lead capture stay consistent. Embed the quiz and use webhooks to get the images and choices.

### Is the API free?

Creating a sandbox is free and needs no account. After the jeweler claims it, their ShowroomPro plan applies. See [pricing](https://www.showroompro.ai/pricing).

### Is there an SDK?

Not yet. The API is plain JSON over HTTPS, and the [OpenAPI spec](https://www.showroompro.ai/openapi.json) can generate a client in most languages.

---

Source: https://www.showroompro.ai/engagement-ring-configurator-api · Last updated 2026-10-16 · All docs: https://www.showroompro.ai/llms.txt