> ## Documentation Index > Fetch the complete documentation index at: https://docs.tryvox.co/llms.txt > Use this file to discover all available pages before exploring further. # 고객 조회 > 인증된 조직의 고객 한 명을 조회합니다. 프로필, 식별자, 인터랙션 요약과 에이전트별 활성 메모리를 반환합니다. 메모리는 고객 단건 조회에만 포함됩니다. 목록, 식별자 검색, 생성, 수정, 병합 응답에는 포함되지 않습니다. 다른 조직의 고객 ID는 404 `CUSTOMER_NOT_FOUND`로 처리합니다. ## OpenAPI ````yaml /api-reference/v3/openapi.json get /customers/{customer_id} openapi: 3.1.0 info: title: vox.ai API description: > vox.ai API v3 ### v3 공개 계약 규칙 - 인증은 `Authorization: Bearer ` 헤더를 사용합니다. 조직 API 키를 Bearer 토큰으로 전달합니다. - 요청과 응답 필드는 기본적으로 `snake_case`를 사용합니다. - `agent.data`는 에이전트 레지스트리와 호환되어야 하므로 `callSettings`, `toolIds`, `builtInTools`, `presetDynamicVariables` 같은 camelCase 필드를 유지합니다. - `_at`으로 끝나는 타임스탬프는 unix milliseconds입니다. 일부 입력값은 호환성을 위해 10~11자리 unix seconds도 허용하고 milliseconds로 정규화합니다. - 캠페인 통화 가능 시간은 분 단위 정수(`start_min` / `end_min`)를 사용합니다. 알림 스케줄은 `HH:MM` 문자열(`start_time` / `end_time`)을 사용합니다. - 응답 객체 자신의 식별자는 `id`입니다. 다른 리소스를 참조하는 필드와 path parameter는 `agent_id`, `call_id`, `telephone_line_id`처럼 명시적인 이름을 사용합니다. - 실패 응답은 `{ "error": { "code", "message", "details" } }` 형태입니다. 가능한 경우 `details.field`, `details.reason`, `details.allowed_values`를 함께 제공합니다. version: 3.0.0 servers: - url: https://client-api.tryvox.co/v3 description: 운영 security: [] paths: /customers/{customer_id}: get: tags: - Customers summary: 고객 조회 description: >- 인증된 조직의 고객 한 명을 조회합니다. 프로필, 식별자, 인터랙션 요약과 에이전트별 활성 메모리를 반환합니다. 메모리는 고객 단건 조회에만 포함됩니다. 목록, 식별자 검색, 생성, 수정, 병합 응답에는 포함되지 않습니다. 다른 조직의 고객 ID는 404 `CUSTOMER_NOT_FOUND`로 처리합니다. operationId: getCustomer parameters: - name: customer_id in: path required: true schema: type: string format: uuid title: Customer Id responses: '200': description: 성공 응답 content: application/json: schema: $ref: '#/components/schemas/CustomerDetailResponse' '400': description: 요청 검증 오류 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validationError: summary: 요청 검증 오류 value: error: code: VALIDATION_ERROR message: Request validation failed. details: field: name reason: must not be blank '401': description: 인증이 필요합니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unauthorized: summary: Bearer 토큰 누락 또는 오류 value: error: code: UNAUTHORIZED message: Authentication is required. details: {} '403': description: 권한이 없습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: 권한이 없습니다. value: error: code: FORBIDDEN message: Permission denied. details: {} '404': description: 리소스를 찾을 수 없습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: notFound: summary: 리소스를 찾을 수 없습니다. value: error: code: RESOURCE_NOT_FOUND message: Resource not found. details: resource: agent '409': description: 충돌이 발생했습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: conflict: summary: 상태 충돌이 발생했습니다. value: error: code: CONFLICT message: The requested operation conflicts with current state. details: current_status: draft '429': description: 요청 한도를 초과했습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: rateLimited: summary: 요청 한도를 초과했습니다. value: error: code: RATE_LIMIT_EXCEEDED message: Too many requests. details: limit: 5 window_seconds: 1 '500': description: 서버 내부 오류가 발생했습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internalError: summary: 서버 내부 오류가 발생했습니다. value: error: code: INTERNAL_ERROR message: Internal server error. details: {} '503': description: 서비스를 일시적으로 사용할 수 없습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: serviceUnavailable: summary: 서비스를 일시적으로 사용할 수 없습니다. value: error: code: SERVICE_UNAVAILABLE message: Service temporarily unavailable. details: {} security: - BearerAuth: [] components: schemas: CustomerDetailResponse: properties: id: type: string title: Id description: 고객 UUID입니다. name: anyOf: - type: string - type: 'null' title: Name description: 고객 이름입니다. note: anyOf: - type: string - type: 'null' title: Note description: 고객 메모입니다. attributes: additionalProperties: true type: object title: Attributes description: 자동 추출한 고객 속성 값입니다. 이름에 해당하는 정의가 없어도 저장된 값을 유지합니다. created_at: type: integer title: Created At description: 리소스 생성 시각입니다. 밀리초 단위 unix timestamp입니다. updated_at: type: integer title: Updated At description: 리소스 수정 시각입니다. 밀리초 단위 unix timestamp입니다. identifiers: items: $ref: '#/components/schemas/CustomerIdentifierResponse' type: array title: Identifiers description: 고객 신원 식별자 목록입니다. metadata: additionalProperties: true type: object title: Metadata description: 고객 메타데이터입니다. interaction_summary: $ref: '#/components/schemas/CustomerInteractionSummary' description: 통화와 채팅 인터랙션의 집계 요약입니다. memory: $ref: '#/components/schemas/MemoryEmbed' description: 에이전트별로 묶은 고객의 활성 메모리입니다. 고객 단건 응답에서만 제공합니다. type: object required: - id - attributes - created_at - updated_at - identifiers - metadata - interaction_summary - memory title: CustomerDetailResponse description: >- 메모리를 포함한 `GET /v3/customers/{id}` 고객 단건 응답입니다. 고객 단건 조회만 활성 메모리 그룹을 불러옵니다. 식별자 검색, 생성, 수정, 병합에서 사용하는 `CustomerResponse`에는 메모리가 없습니다. 따라서 실제 메모리가 없는 것처럼 보이는 빈 그룹을 반환하지 않습니다. ErrorResponse: type: object required: - error title: ErrorResponse description: 모든 실패 응답에서 사용하는 v3 error envelope입니다. examples: - error: code: VALIDATION_ERROR message: Request validation failed. details: field: name reason: must not be blank properties: error: $ref: '#/components/schemas/ErrorDetail' description: 오류 payload입니다. CustomerIdentifierResponse: properties: id: type: string title: Id description: 식별자 UUID입니다. identifier_type: type: string title: Identifier Type description: 식별자 유형입니다. 값은 `phone` 또는 `external_id`입니다. identifier_value: type: string title: Identifier Value description: 정규화된 표준 식별자 값입니다. created_at: type: integer title: Created At description: 리소스 생성 시각입니다. 밀리초 단위 unix timestamp입니다. type: object required: - id - identifier_type - identifier_value - created_at title: CustomerIdentifierResponse description: 고객 신원 식별자 응답입니다. `is_primary`는 제공하지 않습니다. CustomerInteractionSummary: properties: interaction_count: type: integer title: Interaction Count description: 통화와 채팅의 전체 개수입니다. first_interaction_at: anyOf: - type: integer - type: 'null' title: First Interaction At description: 가장 이른 인터랙션 시각입니다. 밀리초 단위 unix timestamp입니다. 인터랙션이 없으면 null입니다. last_interaction_at: anyOf: - type: integer - type: 'null' title: Last Interaction At description: 가장 최근 인터랙션 시각입니다. 밀리초 단위 unix timestamp입니다. 인터랙션이 없으면 null입니다. last_interaction_id: anyOf: - type: string - type: 'null' title: Last Interaction Id description: 가장 최근 인터랙션의 ID입니다. 인터랙션이 없으면 null입니다. last_interaction_type: anyOf: - type: string - type: 'null' title: Last Interaction Type description: 가장 최근 인터랙션의 유형입니다. 값은 `call` 또는 `chat`입니다. 인터랙션이 없으면 null입니다. type: object required: - interaction_count title: CustomerInteractionSummary description: >- 고객의 통화와 채팅 인터랙션을 집계한 요약입니다. 인터랙션 시각은 활동 시각을 나타냅니다. 채팅의 `last_interaction_at`은 유휴 정리 작업으로도 갱신될 수 있으므로 사람이 마지막으로 메시지를 보낸 시각과 다를 수 있습니다. 인터랙션이 없으면 개수는 0이고 시각은 null입니다. MemoryEmbed: properties: items: items: $ref: '#/components/schemas/MemoryGroupResponse' type: array title: Items description: 페이지 항목입니다. type: object required: - items title: MemoryEmbed description: >- 고객 단건 응답에 고객과 에이전트 그룹으로 포함하는 메모리입니다. 활성 메모리를 목록 조회 응답과 같은 `MemoryGroupResponse` 형상으로 에이전트별로 묶습니다. 메모리가 없으면 `items`는 빈 배열입니다. ErrorDetail: type: object required: - code - message - details title: ErrorDetail description: 기계가 읽을 수 있는 v3 오류 상세 정보입니다. examples: - code: VALIDATION_ERROR message: Request validation failed. details: field: name reason: must not be blank properties: code: type: string title: Code description: 기계가 읽을 수 있는 오류 code입니다. message parsing 대신 이 값을 사용합니다. examples: - VALIDATION_ERROR message: type: string title: Message description: 사용자에게 표시할 수 있는 오류 메시지입니다. 프로그램 처리는 `code`를 사용합니다. examples: - Request validation failed. details: type: object title: Details additionalProperties: true description: 구조화된 context입니다. 주로 `field`, `reason`, `allowed_values`를 포함합니다. MemoryGroupResponse: properties: customer_id: type: string title: Customer Id description: 고객 UUID입니다. agent_id: type: string title: Agent Id description: 에이전트 UUID입니다. static: items: $ref: '#/components/schemas/MemoryGroupFactResponse' type: array title: Static description: '`static` tier의 활성 fact 목록입니다. `created_at` 내림차순으로 정렬합니다.' dynamic: items: $ref: '#/components/schemas/MemoryGroupFactResponse' type: array title: Dynamic description: '`dynamic` tier의 활성 fact 목록입니다. `created_at` 내림차순으로 정렬합니다.' type: object required: - customer_id - agent_id - static - dynamic title: MemoryGroupResponse description: >- 활성 fact를 tier별로 나눈 고객과 에이전트 그룹입니다. `static`과 `dynamic` fact는 각각 `created_at` 내림차순으로 정렬합니다. 고객 ID와 에이전트 ID는 그룹에만 표시하고 fact에는 반복하지 않습니다. 목록 조회 응답 항목과 고객 단건 응답의 메모리는 같은 형상을 사용합니다. MemoryGroupFactResponse: properties: id: type: string title: Id description: 메모리 UUID입니다. tier: type: string title: Tier description: 메모리 tier입니다. 값은 `static` 또는 `dynamic`입니다. content: type: string title: Content description: 한 문장으로 구성된 메모리 fact 내용입니다. created_at: type: integer title: Created At description: 리소스 생성 시각입니다. 밀리초 단위 unix timestamp입니다. source_call_id: anyOf: - type: string - type: 'null' title: Source Call Id description: 이 fact의 출처인 통화 UUID입니다. 직접 생성한 경우 null입니다. source_chat_id: anyOf: - type: string - type: 'null' title: Source Chat Id description: 이 fact의 출처인 채팅 UUID입니다. 직접 생성한 경우 null입니다. type: object required: - id - tier - content - created_at title: MemoryGroupFactResponse description: 그룹에 포함된 fact입니다. 고객 ID와 에이전트 ID는 상위 그룹에만 표시합니다. securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: Organization API key description: '조직 API 키를 `Authorization: Bearer ` 형식으로 보냅니다.' ````