Trial generations are priced by this partner to its own users, and each trial is a license with an id. Periodically (for example daily) the partner reports what each trial license owes, with a total. Impersonas takes its percentage and the rest goes to the talent. With a bank account linked the total is debited automatically; without one, sending the report returns a Stripe link to pay.
This app pretends to be a generation partner (like Flora). It talks to the real Impersonas partner API of the platform shown in the banner. Work through the steps in order. Each step says what to click, what the partner's server sends to Impersonas and what Impersonas answers. Compare what you see with the Expected lines.
Start here: the whole process in 5 minutes (only clicks)
This is the short path. Each step has a longer explanation below, with the exact requests and answers for developers.
-
Sign up a buyer. Click Test login (top right). Type a new email, such as
owner+1@example.com, and any company name. Click Log in. -
Confirm on the Impersonas page that opens: click Send code, type
000000, click Verify, then Continue, tick I agree, click I agree. It says Linked. - Come back to this app (the address of this page; the Impersonas page has no back button). Click Test login and type the same email again. You are signed in.
- Buy a trial. On the Impersonas tab click Buy trial on any card, then Create request. In My purchases note the number after Request (the trial license id). Type a prompt and click Generate a couple of times.
- Link a bank account (once). Open Fee reports, click Link bank account, and on the Stripe page choose Test (Non-OAuth), Agree and continue, Continue as guest, the account named Success, Connect account, Set up bank account. Back in the app click Refresh bank account.
-
Send the daily report. Click Add trial license, type the trial license
id and an amount such as
3.00, click Send report. Click Refresh status until it says paid (about 30 seconds on staging). - Check the result in Motor Admin: Trial Generation Reports shows the report as Paid, and Payouts shows the platform fee and the payouts it created. The next sections of this tab say where everything is.
Expected: the report is paid. Each license row shows the percentage and
amount Impersonas keeps (the platform fee), and the rest goes to the agency, less any
talent splits. The percentage is a setting (see "What Impersonas does with the money"),
so it can differ between agencies and Impersonas.
0. Before you start, and how the whole process fits together
-
Platform address: the one in the banner at the top
(
API_BASEbelow). Every path in this guide starts with/api/v1, for exampleAPI_BASE/api/v1/partner/users. -
In the examples,
PARTNER_KEYis the secret key Impersonas gives a partner. This app holds it on its server, so you never type it. A real partner keeps it on its own server. -
On staging the email code is always
000000. No email is sent. Use a fresh email such astester+1@example.comto see onboarding; reuse an email to see sign-in. - Money moves in test mode only: Stripe test bank and test cards. Nothing real is charged or paid.
-
Every call the partner makes carries the partner key in the header
X-Partner-Key: PARTNER_KEY. It is issued by Impersonas and kept on the partner's server, never in the browser. A wrong or missing key always answers401 {"message":"You are not authorized to perform this action."}. -
Errors always come back as JSON
{"message":"..."}with a status code (400bad request,401not authorized,403forbidden,404not found,409conflict,422invalid data).
The full process, in the order of the steps below:
1 Partner reads the catalogue GET /partner/impersonas
2 Partner registers a buyer POST /partner/users
3 Partner starts a handoff, user does the POST /partner/handoffs
Impersonas page (code, company, consent) (user works on the Impersonas page)
4 Partner signs the buyer in POST /partner/authenticate
5 Buyer buys a Trial (partner collects the POST /partner/license_requests
money itself)
6 Buyer generates with the Trial POST /partner/license_usages/reserve
POST /partner/license_usages
7 Partner links its bank account (once) POST /partner/bank_account
8 Each day: partner reports what it owes POST /partner/trial_generation_reports
Impersonas debits the bank account (automatic)
9 Impersonas pays the platform fee, the talent and the agency (automatic)
Only trial generations work this way: the partner is paid by its own client and pays Impersonas afterwards through the daily report. Commercial licenses (step 11) are paid to Impersonas through Stripe.
1. Read the catalogue (what the partner may sell)
- Open the Impersonas tab. Each card is one Impersona with its trial price.
- Click Details on a card to see industries, permissions and assets.
Partner sends
GET API_BASE/api/v1/partner/impersonas?page=1 X-Partner-Key: PARTNER_KEY
Impersonas answers 200
{
"list": [
{
"impersona_id": "AGNCY-ZOR01-IMP01",
"display_name": "zoro angry",
"description": "Fight",
"allowed_industries": [{ "id": 40, "name": "Other" }],
"enabled_permissions": [{ "id": 37, "name": "Merchandising" }],
"availability": { "available": true, "license_requests_limit": 900 },
"assets": [{ "id": 614, "asset_type": "likeness_rights", "price_in_usd": "232.0" }]
}
],
"total_count": 1, "total_pages": 1, "current_page": 1
}
Also available: GET /partner/impersonas/:impersona_id for one Impersona,
and GET /general_data/industries (no key needed) for the industry ids the
buyer can choose from. Results are paginated: page and
per_page (at most 100).
2. A new buyer signs up through the partner (steps 2, 3 and 4 of the process)
- Click Test login, enter a new email and a company name, click Log in.
-
You are sent to the Impersonas page that confirms the user. Click
Send code, enter
000000, click Verify. - Choose Create a new company named ..., click Continue, tick I agree and click I agree again. The page says Linked.
- Go back to the partner app and click Test login again with the same email.
Expected: the second login signs you in directly. Logging in before finishing the Impersonas page never creates an account.
2a. Partner registers the buyer (no account is created yet)
POST API_BASE/api/v1/partner/users
X-Partner-Key: PARTNER_KEY
Content-Type: application/json
{
"external_user_id": "buyer-123",
"email": "tester+1@example.com",
"first_name": "Sam",
"last_name": "Buyer",
"company_name": "Sam Co"
}
Answer 201 {"external_user_id":"buyer-123","status":"pending"}.
Sending the same data again answers 200 (with "status":"linked"
once the user finished step 2c). Different data for an already linked user answers
409. A missing field answers 422 {"message":"Missing parameter
email"}. external_user_id is the partner's own stable id for the user.
2b. Partner starts a handoff (a one-time link for the user)
POST API_BASE/api/v1/partner/handoffs
X-Partner-Key: PARTNER_KEY
Content-Type: application/json
{ "external_user_id": "buyer-123", "purpose": "onboarding" }
Answer 201. The partner sends the user to portal_url.
{
"id": "743a4ec4-ab78-4c10-93b6-164227b9eda5",
"state": "pending",
"purpose": "onboarding",
"external_user_id": "buyer-123",
"expires_at": "2026-11-16T14:17:58.896Z",
"portal_url": "https://staging.impersonas.com/partner/handoff?token=...",
"token": "..."
}
The token is shown only in this answer and expires after 30 minutes. The partner can
follow the handoff with GET /partner/handoffs/:id; its
state moves pending, verified,
company_selected, consented, completed.
2c. The user finishes the Impersonas page (the partner does not call these)
- Email code: the user receives a 6 digit code, valid 10 minutes, 5 tries.
- Company: the user picks an existing client company or creates a new one.
- Consent: the user agrees that the partner may request licenses for them.
- Done: the user, the company and the link to the partner now exist.
2d. Partner signs the buyer in
The partner signs a short-lived token (RS256) with its own private key. It must expire within 5 minutes and carry these claims:
{
"iss": "the partner's issuer, for example eid-co",
"aud": "impersonas",
"sub": "buyer-123",
"iat": 1794840000,
"exp": 1794840240,
"company_type": "client",
"given_name": "Sam",
"family_name": "Buyer"
}
POST API_BASE/api/v1/partner/authenticate
X-Partner-Key: PARTNER_KEY
Authorization: Bearer SIGNED_TOKEN
Content-Type: application/json
{ "company_type": "client" }
Answer 200:
{
"token_type": "Bearer",
"jwt_token": "...",
"expires_at": "2026-11-16T14:48:42Z",
"company_user_id": 310,
"company": { "id": 184, "name": "Sam Co", "company_type": "client" }
}
Keep jwt_token and company_user_id: they are sent on every
buyer call below, as Authorization: JWT_TOKEN (no word Bearer) and
CompanyUserID: 310. Errors:
403 {"message":"This identity is not linked yet. Provision the user and complete
an Impersonas handoff first."} before the user finished 2c, and
401 {"message":"The external user token is invalid or expired."} for a bad
or old token.
3. Buy a Trial (the partner collects the money, no payment to Impersonas)
- On the Impersonas tab pick a card that shows Trial, click Buy trial.
- Choose an industry and the number of generations, click Create request.
- The page jumps to My purchases and highlights the new card.
Expected: the status is approved_and_active at once. No Stripe page opens,
because the partner is paid by its own client.
Partner sends
POST API_BASE/api/v1/partner/license_requests
X-Partner-Key: PARTNER_KEY
Authorization: JWT_TOKEN
CompanyUserID: 310
Idempotency-Key: trial-buyer-123-zoro-001
Content-Type: application/json
{
"impersona_id": "AGNCY-ZOR01-IMP01",
"license_type": "trial",
"industry_id": 40,
"generation_count": 3,
"terms_accepted": true,
"privacy_policy_accepted": true
}
Answer 201:
{
"license_request_id": 723,
"license_type": "trial",
"trial_generation_count": 3,
"license_amount_in_usd": "3.0",
"custom_id": "AGNCY-ZOR01-IMP01-EIDBU-00001",
"status": "approved_and_active"
}
Keep license_request_id: it is the license id used in generation
and in the daily report. Rules and errors:
-
Idempotency-Keyis required (1 to 128 letters, digits, dots, underscores, colons, hyphens), otherwise400. Repeating the same call with the same key replays the first answer; the same key with other data answers409. -
A company can buy one Trial per Impersona:
409 {"message":"Your company has already purchased a Trial for this Impersona."} -
Wrong industry:
422 {"message":"The client industry is invalid."}. Unknown Impersona:404. -
For a percentage priced Trial the partner also sends
generation_revenue_in_usdandpartner_calculated_fee_amount_in_usd.
4. Generate with the Trial (reserve, then report)
- In My purchases open the active Trial, type a prompt, click Generate.
- Repeat until the allowance reaches zero.
Expected: Allowance shows one more used and one fewer remaining each time. When none remain the platform refuses the next generation.
4a. Partner reserves one use before generating
POST API_BASE/api/v1/partner/license_usages/reserve
X-Partner-Key: PARTNER_KEY
Content-Type: application/json
{
"license_request_id": 723,
"impersona_id": "AGNCY-ZOR01-IMP01",
"external_reservation_id": "res-001"
}
Answer 201:
{ "external_reservation_id": "res-001", "status": "reserved",
"expires_at": "2026-11-16T17:26:18Z", "duplicate": false }
4b. Partner reports the finished generation
POST API_BASE/api/v1/partner/license_usages
X-Partner-Key: PARTNER_KEY
Content-Type: application/json
{
"external_generation_id": "gen-001",
"occurred_at": "2026-11-16T17:16:37Z",
"modality": "text",
"authorization_context": "paid_trial",
"external_client_reference": "buyer-123",
"prompt": "A short test prompt",
"protection_method": "watermark",
"billable": true,
"impersonas": [
{ "impersona_id": "AGNCY-ZOR01-IMP01", "generation_cost": 0.5,
"external_reservation_id": "res-001" }
]
}
Answer 201 ("duplicate": true if the same event is sent again):
{
"external_generation_id": "gen-001",
"status": "accepted",
"duplicate": false,
"usages": [
{ "id": 20, "license_request_id": 723, "impersona_id": "AGNCY-ZOR01-IMP01",
"status": "consumed", "generation_cost": "0.5",
"trial_generation_fee_type": "fixed", "trial_generation_fee_amount_in_usd": "1.0" }
]
}
4c. If the generation fails, release the reservation so the use is not lost:
POST /partner/license_usages/res-001/release with body
{}. Answer 200
{"external_reservation_id":"res-001","status":"released",...}.
4d. Check the allowance at any time
GET API_BASE/api/v1/partner/license_requests/723 X-Partner-Key: PARTNER_KEY
{ "id": 723, "license_type": "trial", "client_status": "approved_and_active",
"trial_generation_count": 3,
"trial_generation_usage": { "used_count": 1, "reserved_count": 0, "remaining_count": 2 },
... }
GET /partner/license_requests lists this partner's requests (paginated).
Sending the same external_generation_id with different data answers
409.
5. Link the partner's bank account (once, for automatic payment)
- Open the Fee reports tab. The bank card says no account is linked.
- Click Link bank account. A Stripe page opens.
- Enter an email (if empty) and any name, choose Test (Non-OAuth) as the bank, Agree and continue, Continue as guest, pick the account named Success, click Connect account, then Set up bank account.
- Back in the app click Refresh bank account.
Expected: the card says Linked: STRIPE TEST BANK ending 6789. Reports are debited automatically.
Partner sends (nothing is charged by this call)
POST API_BASE/api/v1/partner/bank_account
X-Partner-Key: PARTNER_KEY
Content-Type: application/json
{ "success_url": "https://partner.example.com/bank-linked",
"cancel_url": "https://partner.example.com/bank-canceled" }
Answer 201 {"stripe_setup_url":"https://checkout.stripe.com/..."}.
The partner sends its person to that address. Then:
GET API_BASE/api/v1/partner/bank_account X-Partner-Key: PARTNER_KEY
200 { "linked": true,
"bank_account": { "id": "pm_...", "bank_name": "STRIPE TEST BANK", "last4": "6789",
"account_type": "checking", "account_holder_type": "individual" } }
404 when no account is linked yet
- Replace: click Replace bank account and repeat the Stripe page. Only the newest account stays; all earlier ones are detached, so exactly one is debited.
-
Unlink:
DELETE /partner/bank_account. Later reports return a Stripe payment link again instead of being debited. - US banks only, in US dollars. Real accounts verify instantly or with micro-deposits in 1 to 2 business days.
6. Send the daily fee report (partner pays Impersonas)
- Open Fee reports. Under New report click Add trial license.
-
Type the Trial license id from step 3 (for example
723) and the amount the partner owes for it (for example3.00). Add more rows for more licenses. There is no limit on the number of rows. - Click Send report. The app also sends the total.
- The report appears under Sent reports. Click Refresh status after a few seconds.
Expected, with a bank account linked: the report goes to processing (the bank payment is clearing), then paid. Each license row shows x% = $..., the platform fee Impersonas takes (the percentage depends on the settings, for example 13%). On staging the test bank clears in about 30 seconds; a real ACH debit takes a few business days.
Partner sends
POST API_BASE/api/v1/partner/trial_generation_reports
X-Partner-Key: PARTNER_KEY
Content-Type: application/json
{
"external_report_id": "day-2026-11-16",
"period_start": "2026-11-16",
"period_end": "2026-11-16",
"total_amount_in_usd": "55.00",
"items": [
{ "license_request_id": 723, "amount_in_usd": "20.00" },
{ "license_request_id": 724, "amount_in_usd": "35.00" }
]
}
-
external_report_id: the partner's own unique id for this report (for example one per day).period_startandperiod_endare optional but must be sent together. -
total_amount_in_usdmust equal the sum of the items. Amounts have at most 2 decimals. Everylicense_request_idmust be a Trial this partner created. -
Without a linked bank account the partner can also send
success_urlandcancel_urlto get a Stripe payment link.
Answer 201, bank account linked:
{
"id": 9,
"external_report_id": "day-2026-11-16",
"status": "processing",
"collection_method": "bank_account",
"charged_automatically": true,
"stripe_checkout_url": null,
"total_amount": "55.0",
"currency": "USD",
"items_count": 2,
"failure_reason": null,
"paid_at": null,
"items": [
{ "license_request_id": 723, "impersona_id": "AGNCY-ZOR01-IMP01", "amount": "20.0",
"platform_fee_percentage": "13.0", "platform_fee_amount": "2.6" },
{ "license_request_id": 724, "impersona_id": "AGNCY-ZOR01-IMP01", "amount": "35.0",
"platform_fee_percentage": "13.0", "platform_fee_amount": "4.55" }
]
}
Without a bank account the answer has "collection_method": "checkout" and
a stripe_checkout_url to pay the exact total (test card
4242 4242 4242 4242, any future date, any CVC).
Report status (status)
awaiting_payment: nothing has been paid yet. With a bank account click Debit bank account; without one click Open Stripe to pay.processing: the bank debit was started and is clearing.paid: the money arrived. Payouts are created.failed: the debit failed;failure_reasonsays why. Click Debit bank account to charge again (the same report sent again does the same).
Follow a report
GET API_BASE/api/v1/partner/trial_generation_reports/9 one report with its items
GET API_BASE/api/v1/partner/trial_generation_reports the list, newest first, with
items_count and no items
X-Partner-Key: PARTNER_KEY
Both answer 200 with the same fields as above; the list is paginated like
the catalogue.
Safe to retry, and what is refused
Same external_report_id, same data 200 the same report is returned, nothing is charged twice
Same external_report_id, other data 409 {"message":"This external_report_id was already used with different data."}
Total not equal to the items 422 {"message":"total_amount_in_usd does not equal the sum of the item amounts."}
A license of another partner 422 {"message":"One or more licenses are not trial licenses created by this partner."}
Wrong or missing partner key 401 {"message":"You are not authorized to perform this action."}
A report that is processing or paid is never charged twice.
7. What Impersonas does with the money, and where to see it
When a report is paid every amount is split, using the percentages stored when the report arrived:
- Platform fee: a percentage that Impersonas sets. The default is in Product Settings; a company (agency) or a single Impersona can have its own, which wins over the default (Impersona first, then company, then default). The same setting is used for license royalties.
- Talent splits: the Impersona's beneficiaries get their percentages of the rest.
- Agency: the company keeps what is left.
Example, with a 13% platform fee: a $3.00 line pays $0.39 platform fee and $2.61 to the agency. The payouts follow the normal payout rules: a 7 day hold, a minimum amount, and a recipient that finished payout setup (Stripe Connect).
Where to look (Impersonas admin) (the full list is in "Where to find things in Motor Admin")
- Motor Admin > Trial Generation Reports: each report, its partner and its status (Awaiting Payment, Processing, Paid, Failed).
- Motor Admin > Payouts: the platform fee and company payouts created from it.
-
Agency view:
GET /talent_agency/trial_generation_paymentslists the amounts reported for the agency's Impersonas, one row per Impersona per report.
Where to find things in Motor Admin
Motor Admin is the Impersonas back office, at
API_BASE/admin. It needs a super admin login (ask Impersonas for access).
The list on the left has every table; open one, or type its name in the search box.
| You want to see | Open | What to look at |
|---|---|---|
| The partner itself | Partners | Name, contact email, Active, commission, the partner's public key. The record page has the buttons Toggle Active Status and Revoke API Key. A partner is created with the + button on the list. |
| A new partner's API key | API_BASE/admin/partner_keys/new |
Pick the partner and click Issue API key. The key is shown once; copy it then. (Activating a partner also emails a key to its contact email.) |
| The buyer the partner registered | Partner Users | One row per buyer: the partner's user id and email. Identity verified at is filled once the buyer finished the Impersonas page (linked). |
| The handoff (the Impersonas page) | Partner Handoffs | The state of each handoff: pending, verified, company selected, consented, completed. |
| The buyer's account and company | Users, Companies | Created when the handoff completes. Search by the email you used. |
| A purchased trial | License Requests | The id (for example 727), type trial, status approved_and_active, the buyer's company and the Impersona. This id is what the report uses. |
| Each generation reported | License Usages | One row per generation, with its status (consumed) and its cost. |
| The partner's daily reports | Trial Generation Reports | One row per report with the partner, the total and the status: Awaiting Payment, Processing, Paid or Failed. Open one to see why a debit failed. |
| The amount per license inside a report | Trial Generation Report Items | The license, the amount, and the platform fee percentage and amount taken. |
| The partner's bank account and Stripe customer | Billing Profiles | The partner's billing profile (linked from its Partners record), with its Stripe customer. The bank account itself is only visible in the Stripe dashboard. |
| The money that was created from a paid report | Payouts | Rows of type platform fee, talent split and company remainder, with the amount and status. They start as pending and are paid after the 7 day hold. |
| Who gets what from an Impersona | Impersona Revenues, Impersona Revenue Splits | The talent percentages that are taken from the agency's share. |
| The default platform fee | Product Settings | The default platform fee percentage. A company or an Impersona can override it in its own Platform fee percentage field (Companies, Impersonas). |
Tip: from a partner's record page, the tabs on the left (Partner users, Partner handoffs, License requests, License usages, Trial generation reports, Payouts) show only that partner's rows.
8. Things that must be refused
- Buy the same Impersona's Trial again with the same company: refused with 409.
- Try to download assets with a Trial: refused. A Trial includes generations only.
- Generate after the allowance is used: refused by the platform.
- Send a wrong code five times on the Impersonas page: that code stops working. Wait a minute, then click Send code for a new one. Too many code requests also block you for a while.
- Send a report with a wrong total, a license of another partner, or the same id with other amounts: refused, see step 6.
9. Optional: a user who already has an Impersonas account
- Log out. Log in with an email that already has an Impersonas account.
- On the Impersonas page, verify the code. The user's existing client companies are listed.
- Continue, consent, then log in again.
Expected: no second account is created and the existing company is reused. The partner never learns whether the email already had an account before the code is verified.
10. Optional: one user, two partners
A user can be linked to several partners. The partner that first created the account stays the acquiring partner, and each purchase is tagged with the partner it was made through. (On staging this needs a second partner key; the partner switcher in the header exists only on a local clone.)
11. Commercial licenses (paid to Impersonas, not through this report)
- Click Buy license on a card, pick a type (single use, term based or pre-approved), an asset and a price.
- The agency reviews it on Impersonas. Negotiation and payment follow the platform rules; the buyer pays Impersonas through Stripe.
- Once the license is
approved_and_active, My purchases shows Show assets; open an asset with Files and download.
Expected: assets are only offered when the license is active, and downloads are recorded on the platform. The partner earns its commission (10% by default) on commercial licenses.
POST API_BASE/api/v1/partner/license_requests (same headers as step 3, with the license_type
and price fields; the answer includes a
Stripe checkout address for the buyer)
GET API_BASE/api/v1/partner/license_requests/:id/assets
GET API_BASE/api/v1/partner/license_requests/:id/assets/:asset_id/download
If something looks wrong
- Cannot sign in / 403: the identity is not linked yet. Finish the Impersonas page (step 2).
- 401 on every call: the partner key is wrong, revoked, or the partner is not active. An admin can check this in Motor Admin > Partners.
- "The external user token is invalid or expired": the signed token is older than 5 minutes, or the issuer, audience or public key saved for the partner do not match.
- Rate limit (429) on the Impersonas page: wait 10 minutes.
- A report stays on processing: real bank debits take days. On staging it should turn paid within a minute; if not, check the Stripe webhook events for the payment.
- Amounts say MISMATCH: note the row and the request id, and report it. That is the kind of bug this app exists to find.