{"openapi":"3.1.0","info":{"title":"ProAgent Assistant API","version":"0.1.0","description":"Use this API only on behalf of a consenting ProAgent user. For image documents, extract text with vision first and send JSON fields."},"servers":[{"url":"https://www.proagent.co.kr"}],"paths":{"/api/assistant/connect/device":{"post":{"operationId":"startProAgentDeviceConnection","summary":"Start ProAgent assistant connection","description":"Creates a device session. Show verification_uri_complete to the user so they can approve in ProAgent.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string","examples":["claude-mobile"]},"scopes":{"type":"array","items":{"type":"string","enum":["clients:write","cases:write","documents:generate"]}}}}}}},"responses":{"201":{"description":"Device session created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceSession"}}}}}}},"/api/assistant/connect/token":{"post":{"operationId":"pollProAgentDeviceToken","summary":"Poll for approved ProAgent bearer token","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["device_code"],"properties":{"device_code":{"type":"string"}}}}}},"responses":{"200":{"description":"Approved connection token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"}}}},"400":{"description":"authorization_pending, access_denied, expired_token, or invalid_grant"}}}},"/api/assistant/clients":{"get":{"operationId":"listProAgentClients","summary":"List ProAgent clients for assistant disambiguation","security":[{"bearerAuth":[]}],"parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Optional name or phone search text."}],"responses":{"200":{"description":"Recent or matching clients","content":{"application/json":{"schema":{"type":"object","properties":{"clients":{"type":"array","items":{"$ref":"#/components/schemas/AssistantClientListItem"}}}}}}}}},"post":{"operationId":"registerProAgentClient","summary":"Register a ProAgent client from extracted text fields","description":"For ID cards and other images, use vision/OCR first, then send JSON text fields. Do not upload the image to this endpoint.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterClientRequest"}}}},"responses":{"200":{"description":"Idempotent existing client returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterClientResponse"}}}},"201":{"description":"Client created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterClientResponse"}}}}}}},"/api/assistant/clients/{clientId}":{"get":{"operationId":"getProAgentClientDetail","summary":"Confirm stored ProAgent client data","description":"Returns the stored client data summary after registration. Use assistantMessage and suggestedNextActions to offer customer signature collection for document drafting.","security":[{"bearerAuth":[]}],"parameters":[{"name":"clientId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Stored client data summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientDetailResponse"}}}},"404":{"description":"Client not found"}}}},"/api/assistant/signature-requests":{"post":{"operationId":"createProAgentSignatureUploadLink","summary":"Create a client signature upload link","description":"Creates a tokenized public page where the selected customer can draw their signature. If no client_id or resolvable client_name is provided, the API returns client candidates for the assistant to ask the user to choose from. Store signatureRequestId and poll the status endpoint if the assistant needs to report completion later.","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSignatureRequest"}}}},"responses":{"201":{"description":"Signature upload link created"},"404":{"description":"Client not found"},"409":{"description":"Client selection required or ambiguous"}}}},"/api/assistant/signature-requests/{signatureRequestId}":{"get":{"operationId":"getProAgentSignatureRequestStatus","summary":"Check client signature upload status","description":"Returns whether the customer has submitted the signature for a previously created upload link. Use assistantMessage when reporting the result to the ProAgent user.","security":[{"bearerAuth":[]}],"parameters":[{"name":"signatureRequestId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Signature request status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignatureRequestStatus"}}}},"404":{"description":"Signature request not found"}}}},"/api/assistant/cases":{"post":{"operationId":"registerProAgentCase","summary":"Create a visa case for an existing client","description":"If the requested visa_code/work_category_code maps to multiple active case types, this endpoint returns 409 case_type_required with candidates and a selectionUrl. Show candidates as chat choices if possible; otherwise send selectionUrl to the ProAgent user.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterCaseRequest"}}}},"responses":{"200":{"description":"Idempotent existing case returned"},"201":{"description":"Case created"},"409":{"description":"Case type selection required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaseTypeRequiredResponse"}}}}}}},"/api/assistant/visa-profiles":{"get":{"operationId":"listProAgentCaseTypes","summary":"List possible ProAgent case types","description":"Use this before case creation when the user gives a visa code or workflow label but not an exact visa_profile_id.","security":[{"bearerAuth":[]}],"parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Optional case type name search."},{"name":"visa_code","in":"query","required":false,"schema":{"type":"string"},"description":"Target visa code, for example E-7-1."},{"name":"work_category_code","in":"query","required":false,"schema":{"type":"string"},"description":"Workflow code such as status_change, period_extend, visa_issue, or workplace_change."}],"responses":{"200":{"description":"Matching case type candidates","content":{"application/json":{"schema":{"type":"object","properties":{"candidates":{"type":"array","items":{"$ref":"#/components/schemas/CaseTypeCandidate"}}}}}}},"400":{"description":"A filter is required"}}}},"/api/assistant/cases/{caseId}/documents":{"get":{"operationId":"listProAgentCaseDocuments","summary":"List case documents and fillable fields","description":"Use this after case creation to enumerate official documents and the fields that are already auto-filled, saved, or still need AI/user input.","security":[{"bearerAuth":[]}],"parameters":[{"name":"caseId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Case document and field list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaseDocumentsResponse"}}}},"404":{"description":"Case not found"}}}},"/api/assistant/case-documents/{caseDocumentId}/form-data":{"patch":{"operationId":"saveProAgentCaseDocumentFormData","summary":"Save case document field values","description":"Save answers for non-auto document fields before calling document generation. Use saveKey values returned by listProAgentCaseDocuments.","security":[{"bearerAuth":[]}],"parameters":[{"name":"caseDocumentId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveCaseDocumentFormDataRequest"}}}},"responses":{"200":{"description":"Saved form data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveCaseDocumentFormDataResponse"}}}},"400":{"description":"Invalid form_data payload"},"404":{"description":"Case document not found"}}},"post":{"operationId":"saveProAgentCaseDocumentFormDataPost","summary":"Save case document field values","description":"Same behavior as PATCH for assistants that cannot send PATCH.","security":[{"bearerAuth":[]}],"parameters":[{"name":"caseDocumentId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveCaseDocumentFormDataRequest"}}}},"responses":{"200":{"description":"Saved form data"},"400":{"description":"Invalid form_data payload"},"404":{"description":"Case document not found"}}}},"/api/assistant/documents/generate":{"post":{"operationId":"generateProAgentDocument","summary":"Generate a draft document for a case document","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateDocumentRequest"}}}},"responses":{"200":{"description":"Generated document path and signed URL"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"DeviceSession":{"type":"object","required":["device_code","user_code","verification_uri_complete"],"properties":{"device_code":{"type":"string"},"user_code":{"type":"string"},"verification_uri":{"type":"string"},"verification_uri_complete":{"type":"string"},"expires_in":{"type":"number"},"interval":{"type":"number"}}},"TokenResponse":{"type":"object","properties":{"access_token":{"type":"string"},"token_type":{"type":"string","const":"Bearer"},"expires_in":{"type":"null"},"scopes":{"type":"array","items":{"type":"string"}}}},"AssistantClientListItem":{"type":"object","required":["id","name_ko"],"properties":{"id":{"type":"string"},"name_ko":{"type":"string"},"name_en":{"type":["string","null"]},"nationality":{"type":["string","null"]},"phone":{"type":["string","null"]},"signature_path":{"type":["string","null"]}}},"RegisterClientRequest":{"type":"object","properties":{"idempotency_key":{"type":"string"},"client":{"type":"object","description":"Text fields extracted by the AI assistant from user-provided documents. name_ko or name_en is required.","required":["name_ko"],"properties":{"name_ko":{"type":"string"},"name_en":{"type":"string"},"birth_date":{"type":"string","format":"date"},"gender":{"type":"string"},"nationality":{"type":"string"},"id_number":{"type":"string"},"foreign_reg_no":{"type":"string","description":"Korean alien registration number. Use this exact key when possible. Accepted aliases include alien_registration_number, alien_registration_no, arc_number, foreign_registration_number, and registration_number."},"passport_number":{"type":"string"},"phone_mobile":{"type":"string"},"email":{"type":"string"},"address_full":{"type":"string"},"address_detail":{"type":"string"},"visa_type":{"type":"string"},"stay_expiry":{"type":"string","format":"date"},"memo":{"type":"string"}},"additionalProperties":true}}},"SuggestedNextAction":{"type":"object","required":["type","message","endpoint","method","body"],"properties":{"type":{"type":"string","enum":["offer_signature_request"]},"message":{"type":"string","description":"Korean message the assistant should use when offering customer signature collection."},"endpoint":{"type":"string","const":"/api/assistant/signature-requests"},"method":{"type":"string","const":"POST"},"body":{"type":"object","required":["client_id"],"properties":{"client_id":{"type":"string"}}}}},"RegisterClientResponse":{"type":"object","required":["clientId","clientName","created","dashboardUrl","assistantMessage","suggestedNextActions"],"properties":{"clientId":{"type":"string"},"clientName":{"type":"string"},"created":{"type":"boolean"},"dashboardUrl":{"type":"string"},"assistantMessage":{"type":"string","description":"Korean message confirming the registration and offering customer signature collection."},"suggestedNextActions":{"type":"array","items":{"$ref":"#/components/schemas/SuggestedNextAction"}}}},"ClientDetailResponse":{"type":"object","required":["clientId","clientName","dashboardUrl","client","assistantMessage","suggestedNextActions"],"properties":{"clientId":{"type":"string"},"clientName":{"type":"string"},"dashboardUrl":{"type":"string"},"client":{"type":"object","properties":{"id":{"type":"string"},"name_ko":{"type":"string"},"name_en":{"type":["string","null"]},"nationality":{"type":["string","null"]},"phone":{"type":["string","null"]},"phone_mobile":{"type":["string","null"]},"email":{"type":["string","null"]},"birth_date":{"type":["string","null"],"format":"date"},"passport_number":{"type":["string","null"]},"visa_type":{"type":["string","null"]},"stay_expiry":{"type":["string","null"],"format":"date"},"signature_path":{"type":["string","null"]},"created_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"}}},"assistantMessage":{"type":"string"},"suggestedNextActions":{"type":"array","items":{"$ref":"#/components/schemas/SuggestedNextAction"}}}},"CreateSignatureRequest":{"type":"object","properties":{"client_id":{"type":"string","description":"Preferred. Exact ProAgent client UUID."},"client_name":{"type":"string","description":"Optional name search when client_id is not known."},"query":{"type":"string","description":"Optional name or phone search when client_id is not known."},"expires_in_seconds":{"type":"number","default":604800,"description":"Upload link TTL. Maximum is 30 days."}}},"SignatureRequestStatus":{"type":"object","required":["signatureRequestId","status","clientId","clientName","signatureStored","dashboardUrl","expiresAt","assistantMessage"],"properties":{"signatureRequestId":{"type":"string"},"status":{"type":"string","enum":["pending","submitted","expired","revoked"]},"clientId":{"type":"string"},"clientName":{"type":"string"},"signatureStored":{"type":"boolean"},"storagePath":{"type":["string","null"]},"dashboardUrl":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"submittedAt":{"type":["string","null"],"format":"date-time"},"assistantMessage":{"type":"string","description":"Korean message the assistant can relay to the ProAgent user."}}},"RegisterCaseRequest":{"type":"object","required":["client_id"],"properties":{"idempotency_key":{"type":"string"},"client_id":{"type":"string"},"visa_profile_id":{"type":"string","description":"Preferred when known. Use a candidate visa_profile_id returned by /api/assistant/visa-profiles or by a previous case_type_required response."},"visa_profile_name":{"type":"string","description":"Exact or partial active ProAgent case type name."},"visa_code":{"type":"string","description":"Target visa code, for example E-7-1."},"work_category_code":{"type":"string","description":"Workflow code such as status_change, period_extend, visa_issue, or workplace_change."},"submission_type":{"type":"string","enum":["offline","electronic"]},"location_type":{"type":"string"},"application_type":{"type":"string"},"has_visa":{"type":"boolean"},"fee":{"type":"number"},"payment_method":{"type":"string"},"memo":{"type":"string"}}},"CaseTypeCandidate":{"type":"object","required":["visa_profile_id","name","document_count"],"properties":{"visa_profile_id":{"type":"string"},"name":{"type":"string"},"visa_code":{"type":["string","null"]},"visa_name_ko":{"type":["string","null"]},"work_category_code":{"type":["string","null"]},"work_category_name":{"type":["string","null"]},"document_count":{"type":"number"}}},"CaseTypeRequiredResponse":{"type":"object","required":["status","message","candidates","selectionUrl","suggestedNextActions"],"properties":{"status":{"type":"string","const":"case_type_required"},"message":{"type":"string"},"candidates":{"type":"array","items":{"$ref":"#/components/schemas/CaseTypeCandidate"}},"selectionUrl":{"type":"string","description":"Browser fallback for the ProAgent user. Use this when the assistant chat UI cannot render candidate buttons."},"suggestedNextActions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"select_case_type"},"message":{"type":"string"},"options":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"body":{"$ref":"#/components/schemas/RegisterCaseRequest"}}}},"fallbackUrl":{"type":"string"}}}}}},"CaseDocumentField":{"type":"object","required":["id","label","dataKey","type","source","valueStatus","saveKey","fillableByAi"],"properties":{"id":{"type":"string"},"label":{"type":"string"},"dataKey":{"type":"string"},"type":{"type":"string"},"page":{"type":["number","null"]},"section":{"type":["string","null"]},"choiceGroup":{"type":["string","null"]},"choiceValue":{"type":["string","null"]},"box":{"type":["object","null"],"additionalProperties":true},"source":{"type":"string","enum":["pdf_authoring_db","pdf_authoring_file","form_fields_v2","form_fields_legacy","document_template_mappings"]},"valueStatus":{"type":"string","enum":["saved","auto","static","needs_input","not_bindable"]},"value":{"type":["string","null"]},"saveKey":{"type":"string","description":"Use this key in form_data when saving an answer. For custom PDF fields this is usually extra:{fieldId}."},"fillableByAi":{"type":"boolean"}}},"CaseDocumentItem":{"type":"object","required":["caseDocumentId","documentId","name","fields","fieldSummary","missingFields"],"properties":{"caseDocumentId":{"type":"string"},"caseId":{"type":"string"},"documentId":{"type":"string"},"name":{"type":"string"},"kind":{"type":["string","null"]},"requiredBy":{"type":["string","null"]},"fillType":{"type":["string","null"]},"status":{"type":["string","null"]},"formCode":{"type":["string","null"]},"fieldSource":{"type":["string","null"]},"fieldSummary":{"type":"object","properties":{"total":{"type":"number"},"auto":{"type":"number"},"saved":{"type":"number"},"needsInput":{"type":"number"},"notBindable":{"type":"number"}}},"fields":{"type":"array","items":{"$ref":"#/components/schemas/CaseDocumentField"}},"missingFields":{"type":"array","items":{"$ref":"#/components/schemas/CaseDocumentField"}},"generateEndpoint":{"type":"string"},"saveFormDataEndpoint":{"type":"string"}}},"CaseDocumentsResponse":{"type":"object","required":["caseId","title","clientId","clientName","documents"],"properties":{"caseId":{"type":"string"},"title":{"type":"string"},"clientId":{"type":"string"},"clientName":{"type":"string"},"documents":{"type":"array","items":{"$ref":"#/components/schemas/CaseDocumentItem"}}}},"SaveCaseDocumentFormDataRequest":{"type":"object","required":["form_data"],"properties":{"form_data":{"type":"object","additionalProperties":true,"description":"Field values keyed by saveKey from CaseDocumentField."},"merge":{"type":"boolean","default":true,"description":"When false, replace existing case_documents.form_data instead of merging."}}},"SaveCaseDocumentFormDataResponse":{"type":"object","required":["caseDocumentId","caseId","savedFormData","generateEndpoint"],"properties":{"caseDocumentId":{"type":"string"},"caseId":{"type":"string"},"savedFormData":{"type":"object","additionalProperties":true},"generateEndpoint":{"type":"string"}}},"GenerateDocumentRequest":{"type":"object","required":["case_document_id"],"properties":{"case_id":{"type":"string"},"case_document_id":{"type":"string"},"form_data":{"type":"object","additionalProperties":true}}}}}}