Embed Orgvatar V-Avatars into your platform
This guide is for developers at platforms like 2percent.ai and Yassu.ai who want to embed Orgvatar's Virtual HR Manager (Ava Chen) directly into their platform. Your users can consult with Ava, receive a Virtual Org Blueprint, and subscribe to Orgvatar -- all without leaving your platform.
Get your Partner API Key
Go to Settings > API & Integrations in your Orgvatar dashboard and generate a Partner API key. Keep it secret -- never expose it in frontend code.
Provision your users
When a user on your platform wants to use Orgvatar, call the sync endpoint to provision them. This creates their startup profile in Orgvatar and returns a startupId.
Create an embed session
Generate a short-lived embed token for the user. Use this token to build the embed URL and load it in an iframe inside your platform.
Listen for events
The embedded Ava chat sends postMessage events to your parent window. Listen for consultation completion and subscription events to update your UI.
Handle the subscription webhook
When a user subscribes to Orgvatar after the consultation, Orgvatar fires a webhook to your registered endpoint with the subscription details.
Generate a Partner API key in Settings > API & Integrations. Store it securely in your backend environment variables as ORGVATAR_API_KEY.
Security
Never expose your Partner API key in frontend code or client-side JavaScript. All API calls must be made from your backend server.
# Verify your API key is working
curl https://orgvatar.ai/api/v1/partners/validate-key \
-H "Authorization: Bearer YOUR_PARTNER_API_KEY"
# Response
{
"valid": true,
"startup": null,
"plan": "growth",
"keyName": "2percent.ai Integration",
"connectedAt": "2026-03-13T10:00:00.000Z"
}| Method | Endpoint | Purpose | Auth |
|---|---|---|---|
| GET | /api/v1/partners/validate-key | Verify your API key | Bearer |
| POST | /api/v1/partners/users/sync | Provision a user | Bearer |
| POST | /api/v1/partners/sessions/create | Create embed session token | Bearer |
| GET | /api/v1/partners/sessions/:token/status | Poll session / subscription status | Bearer |
| POST | /api/v1/partners/checkout/create | Create Stripe checkout for a user | Bearer |
| GET | /api/v1/embed/session?token=... | Validate embed token (frontend) | Token |
| POST | /api/v1/embed/chat | Send message to Ava (frontend) | Token |
| POST | /api/v1/embed/checkout | Create checkout from embed (frontend) | Token |
Get your Partner API key, follow the 5 steps above, and your users will be consulting with Ava within the hour.
Questions? Email [email protected]