ProAgent Assistant API

Quick Start For AI Assistants

1. Start a device session with POST https://www.proagent.co.kr/api/assistant/connect/device.
2. Show verification_uri_complete to the user and wait for approval.
3. Poll POST https://www.proagent.co.kr/api/assistant/connect/token with the device_code.
4. Use the returned Authorization: Bearer pa_live_... token for client, case, and document APIs.

Recommended Assistant Workflow

1. Connect with the device flow and get the approved bearer token.
2. Register or find the client from extracted text fields.
3. Resolve the case type, using chat choices or selectionUrl when ambiguous.
4. Create the case, then immediately list case documents and fields.
5. Ask only for fields marked needs_input or fillableByAi.
6. Save answers with each field's saveKey.
7. Generate the draft document and report the ProAgent review location.
8. Create signature links or request extra materials only when still needed.

Assistants may draft ordinary descriptive fields from conversation context, but must not invent official identity numbers, passport values, registration numbers, birth dates, addresses, signatures, seals, or legally sensitive facts.

When The User Provides An Image

If the user provides an ID card, passport, alien registration card, business registration certificate, or other case material, use your own vision/OCR capability to extract text fields first. Do not upload the image to /api/assistant/clients. Send extracted text as JSON.

POST https://www.proagent.co.kr/api/assistant/clients
Authorization: Bearer pa_live_...
Content-Type: application/json

{
  "idempotency_key": "client-from-id-card-20260527-001",
  "client": {
    "name_ko": "홍길동",
    "name_en": "HONG GILDONG",
    "birth_date": "1990-01-01",
    "gender": "M",
    "nationality": "KOREA",
    "id_number": "900101-1234567",
    "foreign_reg_no": "980716-1234567",
    "phone_mobile": "010-0000-0000",
    "address_full": "서울특별시 ...",
    "passport_number": "M12345678",
    "visa_type": "E-7"
  }
}

Use foreign_reg_no for a Korean alien registration number. Accepted aliases include alien_registration_number, arc_number, and registration_number.

If a field is unreadable or uncertain, omit it or ask the user to confirm. Never invent official identity values.

문서작성시 편리하게 고객서명도 직접 관리할 수 있어.
고객이 옆에 없어도 고객에게 카톡같은 SNS로 웹링크 하나 주고 고객이 서명을 할 수 있는 구조야.
그것도 해줄까?

Case Creation

After registering or finding a client, create a case with POST /api/assistant/cases. Prefer an exact visa_profile_id when known. If the user only gives a visa code and workflow, send visa_code and work_category_code.

POST https://www.proagent.co.kr/api/assistant/cases
Authorization: Bearer pa_live_...
Content-Type: application/json

{
  "idempotency_key": "case-e7-20260527-001",
  "client_id": "client-uuid",
  "visa_code": "E-7-1",
  "work_category_code": "status_change",
  "submission_type": "offline",
  "location_type": "domestic",
  "has_visa": true
}

If ProAgent returns 409 case_type_required, show the returned candidates as choices in the chat UI. If your chat UI cannot show choices, send the returned selectionUrl to the ProAgent user. The browser page lets the logged-in user choose the correct case type and creates the case.

GET https://www.proagent.co.kr/api/assistant/visa-profiles?visa_code=E-7-1&work_category_code=status_change
Authorization: Bearer pa_live_...

Document Lists And Fields

After a case is created, call GET /api/assistant/cases/{caseId}/documents. The response lists the case documents and each document field. ProAgent prefers official PDF authoring metadata from pdf_authoring_fields, then falls back to generated field-spec files.

GET https://www.proagent.co.kr/api/assistant/cases/case-uuid/documents
Authorization: Bearer pa_live_...

Fields with valueStatus: "needs_input" or fillableByAi: true can be collected by the assistant. Save answers with the returned saveKey, then generate the document.

PATCH https://www.proagent.co.kr/api/assistant/case-documents/case-document-uuid/form-data
Authorization: Bearer pa_live_...
Content-Type: application/json

{
  "form_data": {
    "case.workplace_new": "ABC Korea Co., Ltd.",
    "extra:integrated_application.application_type.engage_activities.desired_status": "E-7-1"
  }
}

Customer Signature Links

If the user asks for a customer signature upload link, call POST /api/assistant/signature-requests. Provide a client_id when known. If the client is missing or ambiguous, the API returns candidate clients so the assistant can ask the user which customer to use. Store signatureRequestId from the created response and call GET /api/assistant/signature-requests/{signatureRequestId} later to check whether the customer submitted the signature.

POST https://www.proagent.co.kr/api/assistant/signature-requests
Authorization: Bearer pa_live_...
Content-Type: application/json

{
  "client_id": "client-uuid"
}

GET https://www.proagent.co.kr/api/assistant/signature-requests/request-uuid
Authorization: Bearer pa_live_...

{
  "status": "submitted",
  "assistantMessage": "HONG GILDONG 고객 서명이 ProAgent에 잘 저장됐어."
}

AI Safety Q&A

Discovery Documents