문서 리스트 조회 API(GET /documents)를 통해 계정이 조회 가능한 문서의 목록을 조회할 수 있습니다. 필터·메타데이터 조건으로 필요한 문서만 골라 가져오고, 원하는 기준으로 정렬할 수 있습니다.

1. 기본 호출과 페이지네이션

offset과 limit 파라미터로 원하는 범위의 목록을 불러옵니다.

curl --get 'https://api.modusign.co.kr/documents' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic {인코딩된 API-KEY}' \
  --data-urlencode 'offset=0' \
  --data-urlencode 'limit=10'

예로 ?offset=320&limit=10 의 파라미터는 33페이지의 10개의 문서를 불러옵니다.

응답 구조

응답은 조건에 맞는 전체 개수(count)와 이번 요청으로 불러온 문서 목록(documents)으로 구성됩니다. 전체 페이지 수는 count를 limit으로 나눈 값을 올림하여 계산할 수 있습니다. (예: count가 125, limit이 10이면 13페이지)

{
  "count": 125,
  "documents": [
    {
      "id": "{문서 ID}",
      "title": "2026 근로계약서_김모두",
      "status": "COMPLETED",
      "requester": {
        "email": "[email protected]",
        "name": "홍길동"
      },
      "createdAt": "2026-10-01T09:00:00.000Z",
      "startedAt": "2026-10-01T09:01:00.000Z",
      "updatedAt": "2026-10-02T10:30:00.000Z",
      "file": {
        "downloadUrl": "{다운로드 링크}"
      },
      "metadatas": [
        { "key": "teamCode", "value": "HR" }
      ],
      "labels": [
        { "id": "{라벨 ID}", "name": "인사", "description": "인사팀 문서" }
      ]
    }
  ]
}

위 예시는 이해를 돕기 위해 일부 필드를 생략했습니다. 전체 필드는 문서 리스트 조회 API를 확인하세요.

응답의 status에는 아래 값이 올 수 있습니다.

2. 조건 지정과 정렬

필요한 문서만 조회하려면 아래 파라미터를 함께 사용하세요. 각 파라미터의 구문과 예시는 해당 가이드에서 확인할 수 있습니다.

orderBy를 생략하면 최근 활동일 내림차순(updatedAt desc)으로 정렬됩니다.

3. API 호출 시 주의사항

• 필요한 문서만 조회하세요. 문서 리스트 조회 API는 High-cost API로, 분당 150회·초당 5회로 제한됩니다(무료 체험 계정에서는 분당 5회·초당 1회). 한도를 초과하면 429 오류와 X-Retry-After 헤더(재시도까지 대기할 시간, 초)가 응답됩니다. 자세한 내용은 API Rate Limit 정책 안내를 참고하세요.
• 문서 상태 변화는 Webhook으로 받는 것을 권장합니다. 서명 완료 여부를 확인하려고 목록 조회나 상세 조회를 주기적으로 반복 호출(폴링)하면 호출 한도를 빠르게 소모합니다. Webhook으로 이벤트를 받은 뒤 필요한 문서만 조회하세요.
• API KEY는 서버사이드에서만 사용하세요. 브라우저 등 클라이언트에 노출하지 마세요.

조회 범위와 권한

• 목록 조회 결과에는 API 키를 발급한 계정이 조회할 수 있는 문서만 포함됩니다. API 키는 워크스페이스가 아니라 멤버 계정 단위로 발급됩니다.
• 이 범위 밖의 문서 ID로 문서 상세 조회 등의 API를 호출하면 403 Forbidden이 응답됩니다. 다음과 같은 경우가 해당됩니다.
  • 다른 계정 또는 다른 워크스페이스에서 요청한 문서
  • 공유받지 않은 문서
  • 삭제되었거나 존재하지 않는 문서
• 문서 ID는 가능하면 목록 조회 결과나 Webhook 이벤트로 받은 값을 사용하세요.

자주 발생하는 오류

4. 자주 묻는 질문

{
  "statusCode": 403,
  "message": "Forbidden",
  "error": "Forbidden"
}