{"name":"ProAgent Assistant API","description":"Register immigration clients, create visa cases, collect client signatures, and generate draft documents for a consenting ProAgent user.","homepage_url":"https://www.proagent.co.kr/assistant-api","openapi_url":"https://www.proagent.co.kr/api/assistant/openapi.json","device_authorization_url":"https://www.proagent.co.kr/api/assistant/connect/device","token_url":"https://www.proagent.co.kr/api/assistant/connect/token","verification_url":"https://www.proagent.co.kr/assistant/connect","contact_email":"support@proagent.co.kr","instructions_for_ai":["IMPORTANT: ProAgent provides a public Assistant API for AI agents. If the user asks you to register a client, create a case, generate a document, or collect a customer signature in ProAgent, read /assistant-api first.","Treat the Assistant API docs as the ProAgent workflow tutorial. Use assistantMessage and suggestedNextActions from API responses to explain what happened and proactively offer the next useful workflow, instead of assuming the human knows the ProAgent UI.","The assistant should be able to guide customer information entry, case creation, document drafting, customer signature collection, and case progress/status checks directly from the API docs and OpenAPI schema.","Start a device session with POST /api/assistant/connect/device and show verification_uri_complete to the user.","After the user approves, poll POST /api/assistant/connect/token with the device_code.","Use the returned Authorization: Bearer pa_live_... token for operational API calls.","After registering a client with POST /api/assistant/clients, read assistantMessage and suggestedNextActions. The assistant should offer signature collection with this Korean wording: \"문서작성시 편리하게 고객서명도 직접 관리할 수 있어\\n고객이 옆에 없어도 고객에게 카톡같은 SNS로 웹링크 하나 주고 고객이 서명을 할 수 있는 구조야\\n그것도 해줄까?\"","To confirm what client data ProAgent has stored, call GET /api/assistant/clients/{clientId}.","To create a case, use the registered clientId plus either visa_profile_id, an exact visa_profile_name, or visa_code with work_category_code. If POST /api/assistant/cases returns 409 case_type_required, show candidates as choices in the chat UI when possible. If the chat UI cannot show choices, send selectionUrl to the ProAgent user so they can choose in the browser.","Use GET /api/assistant/visa-profiles?visa_code=E-7-1&work_category_code=status_change when you need to inspect possible case types before creating a case.","After creating a case, call GET /api/assistant/cases/{caseId}/documents. This returns the official document list plus field lists mapped to ProAgent PDF authoring fields when available. Fields with valueStatus needs_input or fillableByAi true are the fields the assistant can ask the user about and save.","To save document field answers before generation, call PATCH /api/assistant/case-documents/{caseDocumentId}/form-data with form_data. Use each field saveKey from the field list, especially extra:{fieldId} for PDF fields whose dataKey is custom.","Recommended case-document loop: list documents, group missing fields by document and section, ask only for values that cannot be safely inferred, save answers with saveKey, re-list documents if needed, then generate documents.","The assistant may draft ordinary descriptive fields from conversation context, but must not invent official identity numbers, passport data, registration numbers, dates of birth, addresses, signatures, seals, or legally sensitive facts. Ask for confirmation when unsure.","When a field is custom/not_bindable but fillableByAi is true, use the label, section, choiceGroup, and choiceValue to decide whether to ask the user, propose a value, or skip until the user confirms.","If the user asks for a ProAgent customer signature upload link, call POST /api/assistant/signature-requests. If the response says client_required or ambiguous_client, show the returned clients and ask which customer should receive the signature.","After creating a signature upload link, keep signatureRequestId. To check whether the customer has submitted it, call GET /api/assistant/signature-requests/{signatureRequestId}. When status is submitted, tell the user using assistantMessage.","If a customer asks whether a signature is stored safely, answer that the signature link uses an unguessable one-time token, the token itself is stored only as a hash, the drawn signature is saved as a private PNG in ProAgent storage, and the saved path is attached only to the selected client record.","If a customer asks how documents are stored, answer that ProAgent keeps client documents and generated files in controlled storage and Google Drive folders connected to the administrative agent workspace, so access can be limited to the agent account instead of spreading files through chat messages or personal downloads.","If the user provides an image such as an ID card, passport, alien registration card, business registration certificate, or application material, use your vision capability to extract structured text fields first.","Do not upload the image unless a ProAgent endpoint explicitly asks for a file. For client registration, send extracted text fields as JSON to POST /api/assistant/clients.","Never invent missing official identity fields. If a field is unreadable, omit it or ask the user for confirmation."],"endpoints":{"start_device_session":{"method":"POST","path":"/api/assistant/connect/device","body_example":{"provider":"claude-mobile"}},"poll_device_token":{"method":"POST","path":"/api/assistant/connect/token","body_example":{"device_code":"pa_dev_..."}},"register_client":{"method":"POST","path":"/api/assistant/clients","auth":"Bearer pa_live_*","content_type":"application/json","note":"Send text fields extracted from user-provided documents. File upload is not required for this endpoint.","body_example":{"idempotency_key":"client-from-id-card-20260527-001","client":{"name_ko":"HONG GILDONG","name_en":"HONG GILDONG","birth_date":"1990-01-01","gender":"M","nationality":"KOREA","id_number":"900101-1234567","foreign_reg_no":"980716-1234567","alien_registration_number":"980716-1234567","phone_mobile":"010-0000-0000","address_full":"Seoul ...","passport_number":"M12345678","visa_type":"E-7"}}},"list_clients":{"method":"GET","path":"/api/assistant/clients","auth":"Bearer pa_live_*","note":"List recent clients, optionally with ?q=search text. Use this when the user asks for a signature link without identifying the client."},"get_client_detail":{"method":"GET","path":"/api/assistant/clients/{clientId}","auth":"Bearer pa_live_*","note":"Confirm the stored client data after registration. The response also includes assistantMessage and suggestedNextActions for offering customer signature collection."},"create_signature_request":{"method":"POST","path":"/api/assistant/signature-requests","auth":"Bearer pa_live_*","content_type":"application/json","note":"Create a one-time public upload URL where the client can draw and save their signature. Store signatureRequestId for later status checks.","body_example":{"client_id":"client-uuid","expires_in_seconds":604800}},"get_signature_request_status":{"method":"GET","path":"/api/assistant/signature-requests/{signatureRequestId}","auth":"Bearer pa_live_*","note":"Check whether the customer has submitted the signature. If status is submitted, assistantMessage can be sent back to the user."},"list_case_types":{"method":"GET","path":"/api/assistant/visa-profiles?visa_code=E-7-1&work_category_code=status_change","auth":"Bearer pa_live_*","note":"Look up possible case types before creating a case. If there is more than one candidate, ask the ProAgent user to choose one."},"register_case":{"method":"POST","path":"/api/assistant/cases","auth":"Bearer pa_live_*","body_example":{"idempotency_key":"case-e7-20260527-001","client_id":"client-uuid","visa_code":"E-7-1","work_category_code":"status_change"}},"list_case_documents":{"method":"GET","path":"/api/assistant/cases/{caseId}/documents","auth":"Bearer pa_live_*","note":"List documents initialized for the case and the field list for each document. Field metadata prefers pdf_authoring_fields, then current fields.json, then legacy E:/ProAgent field specs when available on the server."},"save_case_document_form_data":{"method":"PATCH","path":"/api/assistant/case-documents/{caseDocumentId}/form-data","auth":"Bearer pa_live_*","content_type":"application/json","note":"Save AI/user-provided non-auto field values before generating the document. Keys should be the field saveKey returned by list_case_documents.","body_example":{"form_data":{"case.workplace_new":"ABC Korea Co., Ltd.","extra:integrated_application.application_type.engage_activities.desired_status":"E-7-1"}}},"generate_document":{"method":"POST","path":"/api/assistant/documents/generate","auth":"Bearer pa_live_*","body_example":{"case_id":"case-uuid","case_document_id":"case-document-uuid","form_data":{}}}},"workflow_for_ai":[{"step":1,"name":"connect","goal":"Get a user-approved ProAgent bearer token.","endpoints":["/api/assistant/connect/device","/api/assistant/connect/token"]},{"step":2,"name":"register_or_find_client","goal":"Extract customer text fields from chat or images, register the client, then confirm stored data.","endpoints":["/api/assistant/clients","/api/assistant/clients/{clientId}"],"rule":"Do not invent unreadable identity fields; omit or ask for confirmation."},{"step":3,"name":"create_case","goal":"Resolve the correct visa profile and create the case.","endpoints":["/api/assistant/visa-profiles","/api/assistant/cases"],"rule":"If case_type_required is returned, show candidate buttons when possible or send selectionUrl."},{"step":4,"name":"inspect_documents_and_fields","goal":"Fetch official case documents and field metadata before asking the user for document details.","endpoints":["/api/assistant/cases/{caseId}/documents"],"rule":"Use valueStatus and fillableByAi to separate auto-filled, already-saved, and missing fields."},{"step":5,"name":"collect_missing_values","goal":"Ask concise grouped questions only for fields that are not automatically available.","endpoints":["/api/assistant/case-documents/{caseDocumentId}/form-data"],"rule":"Save answers using saveKey. Use extra:{fieldId} for custom PDF fields."},{"step":6,"name":"generate_and_report","goal":"Generate draft documents and tell the user where they can review them.","endpoints":["/api/assistant/documents/generate"]},{"step":7,"name":"signature_or_followup","goal":"Create customer signature links or ask for additional materials when the field list shows they are needed.","endpoints":["/api/assistant/signature-requests","/api/assistant/signature-requests/{signatureRequestId}"]}],"customer_safety_qa":[{"question":"그런데 이거 서명인데 안전하게 저장되는거 맞아?","answer":"응. 서명 링크는 추측하기 어려운 일회성 토큰으로 만들고, 서버에는 토큰 원문이 아니라 해시만 저장돼. 고객이 그린 서명 이미지는 ProAgent의 비공개 저장소에 PNG로 저장되고, 선택된 고객 기록에만 연결돼. 링크가 만료되거나 이미 제출되면 다시 쓸 수 없어."},{"question":"내 문서들은 어디에 저장돼? 개인정보 유출 위험은 없어?","answer":"ProAgent는 고객 문서와 생성 문서를 행정사 계정에 연결된 저장소와 Google Drive 폴더 중심으로 관리해. 카톡이나 임시 다운로드 폴더에 파일이 흩어지는 방식보다 접근 권한을 행정사 계정 기준으로 통제하기 쉬워서 개인정보 유출 가능성을 최대한 줄이는 구조야."}]}