Skip to main content
An SDK integration has three parts you own and three parts doola runs. Your server and your page never handle the founder’s sensitive data, and doola never handles your checkout.
  1. @doola/js is a small package on your page with no UI of its own. It loads doola’s loader from js.doola.com.
  2. The loader mounts an iframe served from sdk.doola.com and passes it a short-lived customer session that your server minted.
  3. The embedded app inside the iframe runs every screen: the formation wizard, the wait for your payment, document signing and the company dashboard. It talks to the doola API directly.
  4. Your server holds your secret key. It mints customer sessions, reads the company before you charge, and confirms payment to doola.

​
Keys and environments

You use two keys. They come as a pair, one for each environment. Find both in the Partner Portal: the publishable key under SDK → Install, the secret key under Settings → API Keys. Your sandbox account gives you the test pair, and your production account the live one. Test and live are separate stacks with separate data. Never mix a test key with a live one. The loader always loads from https://js.doola.com, whichever key you use.

​
Customer sessions

The iframe acts as one of your customers, never as you. Your server proves who that customer is by minting a customer session with your secret key, for the user who is signed in to your product.
  • Short-lived. A session lasts minutes. The loader asks your route for a new one before the current one expires, so a doola session never outlives your own login.
  • Scoped to one customer. The token can read and submit only that customer’s formation. It cannot call the Partner API.
  • Minted on demand. Your route needs no database. It reads your signed-in user and calls doola. See Create sessions.

​
Who the customer is

doola identifies the customer from what your server sends when it mints the session:
  • externalCustomerId, your own user id, is matched first. Send it: a customer who changes their email with you stays the same doola customer.
  • email is matched next. A new email creates a new customer in your account.
  • Names, phone and country are used only when doola creates the customer.
  • An email that already belongs to a doola account outside your partner account is refused. The loader reports it as email_in_use.

​
One company per customer

Each customer forms one company through the SDK. The iframe decides what to show from that customer’s state, so you mount it the same way every time:

​
The formation lifecycle

A company created through the SDK moves through the same formationSubmissionStatus values as one created through the Partner API, with one state before them: From PENDING on, everything works exactly as in the Partner API: the same company object, the same webhooks, and the same documents.

​
Where data goes

  • The founder’s details, tax ids and signatures are typed into the iframe and sent from there to doola. They never reach your page’s JavaScript, your error tracking, your session replay or your logs.
  • Your page receives one value: the companyId, through onFormed.
  • Your server reads what it needs from the Partner API with your secret key: the company, its owner and the state fee.
See Security and data for the full picture.
Last modified on October 8, 2026