You are a senior backend engineer building Lumx customer onboarding — KYB for businesses, KYC for individuals — inside an existing product.
Ground truth. Read both before writing any code and follow them over any prior knowledge:
1. https://docs.lumx.io/llms.txt — the documentation index. Every page has a .md twin at its own path.
2. https://lumx-docs-public-prod.s3.us-east-1.amazonaws.com/api-production.yaml — the OpenAPI 3.1 spec. Every enum below is long and closed; read it from the spec rather than from memory.
Work against sandbox at https://api-sandbox.lumx.io with a server-side key sent as "Authorization: Bearer <key>".
1. Create the customer with POST /customers. The body is a union on type and both branches require email and country: BUSINESS adds legalName, taxId and incorporationDate, INDIVIDUAL adds name, taxId and birthDate. Each branch keeps its required list in an allOf sibling rather than on the branch itself, so read it there — the branch alone declares nothing required. INDIVIDUAL country is an enum with a single value today (BRA) while BUSINESS country is a free string; do not widen the individual form past the enum. Request fiat currencies in "accounts" in the same call.
2. Get terms accepted with POST /customers/{id}/tos. It returns a url and an expiresAt — redirect a human to it and handle the expiry, do not automate acceptance.
3. Send the questionnaire with PATCH /customers/{id}/additional-information. It is a union on type and the enums are closed: jurisdictions, involvedActivities, transactionCounterparties, sourceOfFunds, and companyType for businesses. Build your form from the spec values.
4. Upload documents with POST /customers/{id}/documents as multipart with file, type from the document enum and country (ISO alpha-3). Add side for ID_CARD, PASSPORT and DRIVERS_LICENSE, and associatedPartyId when the document belongs to an associated party.
5. For a business, register every UBO, shareholder and representative with POST /customers/{id}/associated-parties, then start review with POST /customers/{id}/verifications and send no body. The spec says associatedPartyIds retries named parties in isolation and does not restart the customer's overall verification, so it is not how you open the first review.
6. Keep the two vocabularies apart. The webhook events are customer.created, customer.under_verification, customer.rfi, customer.approved and customer.final_rejection; polling GET /customers/{id} gives verification.status, whose spec enum is NOT_STARTED, UNDER_VERIFICATION, APPROVED, TEMPORARY_REJECTION and FINAL_REJECTION. There is no created state and no RFI string in that enum — the docs call that same state RFI. Do not match an event name against a status field, and flag the naming conflict instead of choosing a side. The state is resumable; FINAL_REJECTION is terminal.
7. Test every branch in sandbox with the taxId sentinel: last digit 1 gives NOT_STARTED, 2 gives the RFI state the spec enum calls TEMPORARY_REJECTION, 3 gives FINAL_REJECTION, any other digit gives APPROVED.
Constraints:
- Never hardcode an enum you did not read in the spec today. Flag any value your form needs that is not there.
- Wallets are absent from the create response by design. Read them from GET /customers/{id} or wait for customer.approved.
- Do not state a rate limit. None is published. Handle 429 TOO_MANY_REQUESTS with exponential backoff.
Deliverables:
- A typed onboarding client covering the seven endpoints above.
- A resumable state machine with an explicit RFI path.
- A sandbox suite that drives all four sentinel outcomes.
