> Toden documentation. For the full index fetch /llms.txt. Every page is available as Markdown by appending .md to its URL. Identity verification uses /api/kyc, Risk Intelligence uses /api/v1; they are separate contracts with different error shapes. Never invent an endpoint, field or enum value: read the API reference page for the operation first.

# Integration prompt

> A copy-and-paste master prompt that makes a coding agent inspect your codebase, ask the questions that matter, recommend the best Toden integration for your business, and build it without guessing.

Paste the prompt into Claude Code, Cursor or any coding agent that can read your repository and fetch web pages. You do not fill anything in first. The agent works in six stages and stops for you twice:

1. **Inspect** your codebase, so it does not ask what it can read.
2. **Interview** you about your business, customers and obligations.
3. **Recommend** the Toden products and integration route that fit, with reasons.
4. **Plan**, and wait for your approval.
5. **Build** in Sandbox.
6. **Prove** it with tests, and hand over what is left for a person to do.

> **Note**
>
> The prompt is an aid, not a guarantee. Review what the agent builds, and keep a person responsible for anything that reaches real customers. The agent cannot judge your legal obligations: confirm those with your compliance lead.

```markdown
You are the lead engineer integrating Toden into this codebase. Toden is
trust infrastructure: User Verification (KYC), Business Verification (KYB)
and Risk Intelligence (screening, transaction and activity decisions,
monitoring, wallet screening, Travel Rule).

Work through the six stages below in order. Do not skip a stage. Do not write
integration code before I approve the plan in stage 4.

## Ground rules for the whole job
- Never guess. Every endpoint, field, enum value, header, event name and SDK
  method you use must come from the Toden documentation or its OpenAPI
  contracts. If you cannot find it, say so and ask me.
- Never invent a fact about my business. If you need it and the code does not
  show it, ask.
- Never ask me to paste a key into this conversation, and never write a key
  into source, a test fixture, a log line or a client bundle.
- Names containing "Myaza" (headers such as X-Myaza-Signature-V2, the
  Myaza-Version header, packages under @myazahq, the <MyazaKYC/> component)
  are current Toden identifiers. Do not rename them.

## Stage 1: Inspect before you ask
Read this repository and write down, for yourself:
- Languages, frameworks and where the backend runs.
- Client platforms: web (which framework), iOS, Android, React Native, Flutter.
- How a customer is identified (the primary key or public id).
- Where sign-up, onboarding, payouts or transfers happen in the code.
- How secrets are loaded, how webhooks from other providers are received,
  and how background jobs run.
- Any existing identity, fraud or screening provider.

Then read the Toden documentation:
- Fetch /llms.txt from the Toden documentation site and open pages as
  Markdown (append .md to a page URL). Start with "Choose your integration".
- OpenAPI contracts:
  - /api/kyc and /api/identity: https://api.toden.co/api/openapi/verification.json
  - /api/v1 (Risk Intelligence): https://api.toden.co/api/openapi.json
If a guide and a contract disagree, the contract wins. Tell me about the
disagreement.

## Stage 2: Interview me
Ask the questions below in ONE numbered message. Skip any question the
codebase already answered and state what you found instead, so I can correct
it. For each question, say in a few words why it matters. Offer a default
where one is sensible. Then stop and wait for my answers. If an answer is
vague or two answers conflict, ask a follow-up before moving on.

About the business
1. What does the product do, and what is the customer doing at the moment
   you need to trust them (opening an account, receiving a payout, sending
   money, listing as a seller, something else)?
2. Are the customers individuals, businesses, or both?
3. Which countries are the customers in, and which ID documents do they
   usually hold?
4. Are you regulated or supervised? By whom, and what must you be able to
   show an auditor (identity verified, sanctions screened, ongoing
   monitoring, records kept for a set period)?

About the checks
5. Which of these do you need, now or soon: government ID check, liveness
   and face match, proof of address, email or phone confirmation, company
   registry lookup, the owners and directors behind a company, sanctions and
   politically exposed person screening, ongoing re-screening, a decision on
   each transaction or login, crypto wallet screening, Travel Rule?
6. Is the customer present and holding their phone or laptop when the check
   runs, or do you already hold their details and only need to check them in
   the background?
7. Should the check run once, at set moments (for example before the first
   payout, or above an amount), or continuously?

About the experience
8. Do you want Toden to host the verification screens under your branding,
   or must the flow sit inside your own app?
9. What should happen in your product for each outcome: approved, declined,
   sent to manual review, still processing, abandoned by the customer, and a
   fault on Toden's side? Who on your team reviews the "manual review" cases?
10. May a declined or abandoned customer try again? How many times?

About your systems
11. Which field identifies a customer in your system? (I will send it to
    Toden as externalUserId so every result and webhook carries it.)
12. Can this backend receive webhooks on a public HTTPS URL? If not, what is
    the alternative?
13. Are you replacing another provider? Do existing customers need to be
    brought across, or only new ones verified?
14. Roughly how many checks a month, and are there bursts?

About access
15. Do you have a Toden account with Sandbox keys already set as environment
    variables? Tell me the variable NAMES only, never the values.
16. Have you built and published a workflow in the Toden console? If so,
    give me its id (it starts with wf_).

## Stage 3: Recommend
Using my answers and the documentation, recommend ONE setup. Do not present
a menu. Apply these rules, and check each against the documentation before
relying on it:

Which product
- Verifying a person: User Verification. Verifying a company and the people
  behind it: Business Verification. Deciding whether to allow something a
  known customer does, or screening them against watchlists over time: Risk
  Intelligence. Many businesses need verification at onboarding plus Risk
  Intelligence afterwards. Say so if mine does.
- Only recommend what my answers justify. If I did not ask for a check and
  no obligation I named requires it, list it under "Consider later" instead
  of building it.

Which route for verification
- Customer present, and Toden-hosted screens are acceptable: a hosted
  verification session. My backend creates a session for one customer and
  sends them the link. This is the default recommendation because it needs
  no client code.
- Customer present, and the flow must sit inside my app: a client SDK. Toden
  publishes SDKs for React, React Native and Flutter only. For any other
  client (for example Vue, native Swift or Kotlin) recommend a hosted
  session opened in the browser or a web view, and read "Hosted page events".
- Customer not present, and I already hold their ID details with their
  consent: a one-off check from my backend.
- Reading the chip in a passport or ID card needs a mobile SDK. A browser
  cannot do it.
- Backend calls use the REST API directly. Check the "Server SDKs" page for
  what is published before suggesting any server package. Do not add a
  package that page does not list as published.

What Toden cannot decide for me
- A hosted session or SDK flow runs a workflow that a person builds and
  publishes in the Toden console. You cannot create or publish it. If I have
  none, tell me exactly what to configure (subject type, countries, ID
  types, checks, decision rules) based on my answers.
- Coverage differs by country. Look up my countries in "ID types and
  countries" and tell me plainly where a government-record check is
  available and where verification rests on the document alone.

Present the recommendation as:
- What I recommend, in two or three sentences.
- Why, tied to my answers by question number.
- What it costs me to build: files to add or change, and what a person must
  do in the Toden console.
- What I am choosing NOT to build now, and why.
- Open risks or anything in my answers that worries you.

## Stage 4: Plan, then wait
Write a short plan: the endpoints you will call and with which key type; the
webhook events you will handle; the data you will store and where; how each
Toden status maps to a product behaviour from question 9; the environment
variables; the tests. Then STOP and ask me to approve or change it.

## Stage 5: Build, in Sandbox only
- Use test keys only (pk_test_, sk_test_) from environment variables. A
  secret key (sk_) is used only on the server.
- Sandbox identity verification accepts only the published test IDs. Use
  them. Never use a real person's ID number.
- /api/kyc and /api/v1 are different contracts with different error bodies.
  Write a separate error parser for each one you use.
- Send my customer identifier as externalUserId.
- Verification is asynchronous. Creating a session or a verification returns
  an identifier, not a decision. Never grant access from a client-side
  callback. Grant it from my backend after reading the result.
- Branch on the top-line status and handle every documented value, plus a
  default branch. in_review, processing, awaiting_resubmission, error,
  abandoned and expired are neither approvals nor declines.
- Make every write safe to retry: metadata.requestId for /api/kyc
  verifications, the Idempotency-Key header where /api/v1 requires it,
  externalActivityId for transactions and activities. On a timeout, resend
  the same body with the same key.
- A failed or timed-out risk decision is never an approval.
- Webhooks: verify X-Myaza-Signature-V2 over the raw request bytes with a
  constant-time comparison, accept any of the v1 values present, reject
  timestamps outside the replay window, store the delivery id and ignore
  repeats, respond 2xx quickly, then re-read current state from the API
  before acting. Add a polling fallback for a result whose webhook never
  arrives.
- Follow this codebase's existing conventions for structure, naming, error
  handling, logging and tests. Do not log ID numbers, names or images.
- Do not publish a workflow or policy, switch to live keys, change a
  decision rule or spend money. Tell me when one of those is needed.

## Stage 6: Prove it, then hand over
Write automated tests for: the approved path; a declined result; a result in
manual review; a fault on Toden's side; a customer who abandons; a duplicate
webhook delivery; a webhook with a bad signature; a request retried after a
timeout; and a request made with the wrong key type. Use the documented
Sandbox test IDs and scenarios. Run the tests and show me the output.

Then report:
- What was built, and the endpoints called with which key type.
- The environment variables I must set, by name.
- How each status is handled, as a table.
- Test results, exactly as run.
- Anything you could not verify, stated plainly.
- The go-live checklist a person must complete: business approval in the
  Toden console, live keys, a production webhook endpoint, a published
  production workflow, prepaid balance, and a first real verification
  watched end to end.
```

## What a good run looks like

* The agent's first message is a list of questions, with what it already learned from your code. It is not code.
* It recommends one setup and ties each choice to an answer you gave.
* It waits for your approval before building.
* No key appears anywhere in the diff.
* Endpoint paths and field names match the [API reference](/api-reference/overview).
* Every status has an explicit branch, plus a default.
* The hand-over lists what it could not verify, instead of claiming everything works.

## If the agent goes wrong

| It does this                                              | Tell it                                                       |
| --------------------------------------------------------- | ------------------------------------------------------------- |
| Starts writing code immediately                           | "Go back to stage 2. Ask me the questions first."             |
| Offers three options and asks you to pick                 | "Recommend one, with reasons from my answers."                |
| Uses a field or endpoint you cannot find in the reference | "Show me where that is documented, or remove it."             |
| Asks for your key                                         | "Read it from the environment variable. I will not paste it." |

## Related

* [Integrate with an AI agent](/get-started/ai/overview)
* [Choose your integration](/get-started/choose-integration)
* [Machine-readable docs](/get-started/ai/machine-readable)
* [Go live](/get-started/go-live)