Build an integration with Lovelio Connect

Lovelio Connect is the self-serve developer platform. You register, create an integration, get a sandbox agency with a working API key in about 20 seconds, build and test against the real API, and submit for review - no calls, no forms, no waiting on us.

Building one integration for one agency - your own, or a client of yours? You do not need any of this. Ask them for an API key from Settings > API keys in their Lovelio account and call the V1 API directly with it. Connect is the route when you want OTHER agencies to find and connect to your app from the public directory: that is what the OAuth client, the certification run and the review are for.

1. Register

Go to lovelio.ai/developers/portal and sign in with your work email. We email you a six-digit code; entering it proves you own a mailbox on your company's domain. The first person from your company founds the workspace and names it - teammates who sign in later with the same domain land in it automatically. Free email providers are not accepted.

2. Create an integration and its sandbox

Click Create integration, name it, then Create sandbox. About 20 seconds later you have:

• A complete Lovelio agency seeded with realistic data: 5 clients, 6 jobs, 18 candidates with full CVs, a pipeline mid-flight across all 9 stages, interviews, submissions and placements.
• One API key with full scopes, shown exactly once. Copy it immediately.

The key is 48 characters, starting sk_test_. After you close that box the portal shows the first 20 characters with the rest masked out: an identifier for the key, never the key itself. We store only a hash, so nobody at Lovelio can read it back to you. If you lose it, Reset sandbox issues a new one (and wipes the sandbox data).

The sandbox is a real Lovelio tenant. Every endpoint, webhook, permission check and rate limit behaves exactly as it will for a paying agency. Two guardrails are permanent: a sandbox can never email a real person, and it never appears in the marketplace.

curl https://us.lovelio.ai/api/v1/jobs \
  -H "Authorization: Bearer sk_test_..."

Your sandbox does not expire. Reset sandbox wipes it and provisions a fresh agency with a new key whenever you want a clean slate.

3. Build

Everything you need is public:

• API reference: /docs/api.md - every endpoint with its parameters, request body and responses, as plain markdown in one fetch. Narrow it with ?tag=Jobs, or get the endpoint list alone with ?index=1. /docs/api is the same content rendered for humans; it draws in the browser, so fetch the .md if you are not running JavaScript.
• Error handling: /docs/agents/error-handling - the envelope, request IDs, retries, idempotency keys, rate-limit headers.
• Webhooks: /docs/agents/webhooks - subscribe with POST /v1/webhooks, verify the HMAC-SHA256 signature, and read the event catalogue at GET /v1/webhooks/events.
• SDKs: /docs/agents/sdks - single-file TypeScript and Python clients.
• AI agents: point any MCP client at the Lovelio MCP server (/docs/mcp) with your sandbox key and let it drive the API for you.

The portal shows live webhook activity for your sandbox: every subscription, every delivery, response codes and retries. Create a subscription, trigger an event (move a candidate's stage, create a job), and watch it arrive.

4. Let agencies connect your app

Lovelio has two developer credentials and they do different jobs. Never swap one for the other:

Writing a test script against your own sandbox? The API key is all you need - one header, no OAuth. Shipping to real agencies? You need the OAuth client as well: an API key belongs to one tenant and can never be issued to anyone else. There is no client ID until you click Create OAuth client - a fresh integration has an API key and no client at all.

Your app ships against the connect flow, not against pasted API keys. In the portal, open your integration and click Create OAuth client. You get:

• A client ID (lc_client_...) you can publish.
• A client secret (lc_secret_...), shown exactly once, inside a ready-made .env block with your other three values. Keep it server-side. Rotate it from the portal if it ever leaks; the old secret stops working the moment the new one appears.

Then give the two ends of the round trip, which the portal asks for together because they are the same kind of thing - a route on your own server, not a page anyone looks at:

• Your connect endpoint. Where Lovelio hands off when an agency clicks Connect. It redirects them straight to the Lovelio approve screen, carrying your own state and PKCE challenge, which is why Lovelio cannot build that URL for you. The agency sees your product's name on the approve screen and nothing of your website.
• Your redirect URIs (https only; http is allowed on localhost while you build). Where Lovelio sends the approved connection so your server can pick up its tokens. /api/oauth/authorize refuses any redirect_uri that is not registered here. Send the agency back into Lovelio when you are done, and the whole thing reads as two clicks inside the app they were already in.

Certification fetches both and fails on a dead one, so a typo costs you a red run rather than a failed connection in front of a real agency.

You do not tick scopes off a list. The Describe what you built step takes one sentence on what your product does, then asks whether it writes anything back into Lovelio and whether it shows or calculates money. Lovelio works out the smallest access set that supports that answer and switches it on for you. Saying it only reads bars every write outright. The picker shows what you have in plain English - "Placements: read" - with the technical scope names one disclosure away, and only the areas your integration uses; everything else is behind Ask for something else.

Take access away for free. Adding something your sentence did not call for costs a written reason, which the reviewer and every connecting agency both read. Access locks while your submission is in review, and widening it after approval forces re-review (see below).

You do not have to write this flow yourself, or even read it. The connect flow step in the portal leads with Copy the setup prompt: one self-contained prompt, with your real values and the reference implementation in it, that an AI coding tool turns into both routes in your own stack. The prompt never carries your client secret - you paste that into your env file yourself. Prefer the source? Behind the For developers disclosure the portal prints the flow with your own client ID, redirect URI and region already in it: a connect route and a callback route, in Node, Python, PHP, Go and cURL, with Copy code and Download both files on each. The four environment values the code reads (LOVELIO_API_URL, LOVELIO_CLIENT_ID, LOVELIO_CLIENT_SECRET, LOVELIO_REDIRECT_URI) are printed as one block at the moment the secret is issued, which is the only moment the secret exists in a browser.

The flow is standard OAuth 2.0 authorization code with PKCE (S256 only, a plain or absent challenge is refused), plus your client secret at the token endpoint:

1. Your connect route makes a random code_verifier, stores it against that browser, and redirects the agency admin to /api/oauth/authorize on the agency's region domain (us, eu or anz.lovelio.ai) with response_type=code, client_id, redirect_uri, scope, state, code_challenge (base64url SHA-256 of the verifier) and code_challenge_method=S256.
2. They sign in if needed, see "Your app wants access to their agency" with the scope list, and approve. Connecting takes an admin - other roles are asked to pass the link on.
3. Your redirect URI receives ?code=...&state=.... Check the state, then exchange the code at POST /api/oauth/token with grant_type=authorization_code, your client_id, client_secret, the code_verifier you stored, and the same redirect_uri. The verifier is what proves the code came back to the server that started the connection, so a stolen code on its own is worth nothing.
4. You get an access token (lc_at_..., one hour) and a refresh token (lc_rt_...). Call the V1 API with Authorization: Bearer lc_at_... - the token carries exactly the scopes the agency granted, enforced on every request. Read scope on the response rather than assuming: a granted set can be narrower than the one you asked for. Refresh with grant_type=refresh_token plus your client credentials; refresh tokens rotate on every use and the window slides while the integration stays active.

The same endpoints, parameters and scopes are declared in the OpenAPI spec at /docs/api under the appOAuth2 security scheme, so a generated client can drive the connection without reading this page.

Webhook subscriptions your app creates with its token belong to the connection: the agency sees them under Settings > Connected apps, and disconnecting disables them and revokes every token immediately.

Test the whole flow before review: the consent screen works against your own sandbox from day one, no approval needed. Click Open sandbox in the portal to sign in to the sandbox agency, then open your authorize URL in the same browser and approve. Once the app is approved, any Lovelio agency can connect to it.

5. Run certification

Before a human reviews your integration, the certification runner has to pass. Click Run certification in the portal: it runs the automated checks against your own sandbox in about a minute and shows you a step-by-step report.

What it checks:

• Auth: requests without a key and with a made-up key are refused; your sandbox key works.
• Error handling: errors carry the standard envelope (code, message, request ID) and writes demand an Idempotency-Key.
• Pagination: cursor pagination pages cleanly with no repeated rows.
• Webhook signing: it creates a subscription, fires the signed test ping, and verifies the HMAC-SHA256 signature end to end, then removes the subscription.
• Your two links: the connect endpoint and every redirect URI are fetched. A 404 or a domain that does not resolve fails the run - that is the typo nobody else catches, because the runner consents through the sandbox door and the directory's Connect button is not exercised until a real agency clicks it. A 401, 403 or redirect passes: a sign-in wall on your connect endpoint is normal. A localhost URI is skipped, not failed - Lovelio cannot reach your machine.
• The connect flow: your OAuth client exists and requests scopes, the token endpoint refuses a wrong client secret, the app connects to your sandbox through the real consent path, a granted scope works and an ungranted one is refused. If certification created the connection it removes it again; if you already connected your app into your sandbox, that connection is reused and left alone.

A red run tells you exactly which step failed and why - fix it and run again. A green run goes stale if you reset the sandbox, recreate the OAuth client, change the scope set, or change either of your two links afterwards, because what was proven is no longer what would ship. Run it again after any of those.

6. Submit for review

When certification is green, fill in the listing (description, category, support link, privacy policy link) and click Submit for review. Your connect endpoint is not asked for here - it was set with your redirect URIs in step 4. Submitting needs a working sandbox and a green, current certification run - the report rides along to the reviewer.

We review by hand and reply by email:

• Approved - your integration goes live in the Lovelio integrations directory straight away.
• Changes requested - the note says exactly what to fix. Editing reopens; fix and resubmit.
• Rejected - the note says why.

7. After approval

A few rules keep the directory honest without slowing you down:

• Listing copy publishes without re-review. Name, description, category, tagline and links stay editable in the portal while the app is approved, and the public directory picks up a save straight away.
• Adding scopes forces re-review; removing them is free. The scope set is what review approved, so asking for MORE takes the app off the directory and back to draft - run certification again and resubmit to relist. Narrowing the set never costs review: the app stays approved and listed. Agencies that already connected keep the scopes they granted either way; only new connections wait for a re-approval. The API asks for confirm_re_review: true on a widening so it never happens by accident.
• New apps start in a limited rollout. Approval sets a cap on active connections, sized by how much access the app requests (read-only apps get a high cap, apps touching email content, documents or marketplace writes a low one). Past the cap, an agency trying to connect sees an "app at capacity" page instead of the consent screen. When you are close, email hello@lovelio.ai and we raise or remove it - your approval email states your starting cap.
• Usage is visible in the portal. The Usage card on your integration shows active connections against the cap, plus the last 30 days of API calls and webhook deliveries across every region your app lives in, sandbox included.
• Lovelio can suspend an app. If an integration misbehaves, suspension takes it off the directory and stops its credentials and webhooks everywhere at once - existing connections stop working until it is resolved. Unsuspending restores the connections exactly as they were.

Questions

Email hello@lovelio.ai. If your integration needs something the API does not cover yet, say so in the submission description - API gaps reported by partners get prioritised.