{"openapi":"3.1.0","info":{"title":"peo.broker onboarding API","version":"1.0.0","description":"Assemble a PEO onboarding package on behalf of a client. Start with agent registration if you do not have a credential. Signing is human-only."},"servers":[{"url":"https:\/\/peo.broker\/api"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}},"paths":{"\/agent-registrations":{"post":{"operationId":"requestAgentRegistration","summary":"Create a pending agent request and email the human for approval.","security":[],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"human_email":{"type":"string","format":"email"},"agent_name":{"type":"string"},"agent_provider":{"type":"string"},"requested_scopes":{"type":"array","items":{"type":"string"}},"agent_redirect_uri":{"type":"string","format":"uri"},"agent_jwks_uri":{"type":"string","format":"uri"},"agent_instance_public_key":{"type":"string"}},"required":["human_email","agent_name"]}}}},"responses":{"202":{"description":"Pending human approval. Show the human the returned user_code - they must type it on the approval page."}}}},"\/agent-registrations\/claim":{"post":{"operationId":"claimAgentCredential","summary":"Claim the scoped credential after the human approves.","security":[],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"pending_registration_id":{"type":"string"},"user_code":{"type":"string"}},"required":["pending_registration_id","user_code"]}}}},"responses":{"200":{"description":"Agent credential issued once."},"202":{"description":"Still pending human approval."},"410":{"description":"Credential already claimed."}}}},"\/onboarding":{"get":{"operationId":"getOnboarding","summary":"Get package state, saved data, checklist, field_guide, question_groups (question wording) and available actions.","responses":{"200":{"description":"Self-describing manifest."}}},"patch":{"operationId":"updateOnboarding","summary":"Set data fields and answer Yes\/No questions (see field_guide and question_groups in the GET response). The signature field is ignored.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"Keyed by data_section (e.g. company, contact)."}},"required":["data"]}}}},"responses":{"200":{"description":"Updated; returns checklist."}}}},"\/onboarding\/documents":{"post":{"operationId":"uploadDocument","summary":"Upload a document into a section folder.","requestBody":{"required":true,"content":{"multipart\/form-data":{"schema":{"type":"object","properties":{"section":{"type":"string","description":"A document_sections key (e.g. census, sbc)."},"file":{"type":"string","format":"binary"}},"required":["section","file"]}}}},"responses":{"201":{"description":"Stored; returns checklist."}}}},"\/onboarding\/submit":{"post":{"operationId":"submitOnboarding","summary":"Submit a package the human has ALREADY signed. Normally unnecessary: signing submits.","responses":{"200":{"description":"Submitted."},"409":{"description":"signature_required - call request-signature instead."},"422":{"description":"Incomplete."}}}},"\/onboarding\/request-signature":{"post":{"operationId":"requestSignature","summary":"Once the checklist is complete, email the human to review and sign. Agents cannot sign; the signature submits the package.","responses":{"200":{"description":"Signature requested."},"422":{"description":"Checklist incomplete."}}}}}}