filter 파라미터를 사용하면 문서 리스트 조회 API와 템플릿 리스트 조회 API에서 조건에 맞는 항목만 골라 조회할 수 있습니다. 필터 구문을 작성한 뒤 URL 인코딩하여 filter 파라미터에 적용해 주세요.

1. 기본 사용법

필터 구문은 반드시 URL 인코딩해서 전달해야 합니다. curl의 --data-urlencode를 사용하면 구문을 그대로 적어도 자동으로 인코딩됩니다.

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' \
  --data-urlencode "filter=status eq 'COMPLETED'"

직접 인코딩하는 경우 아래처럼 변환합니다.

예를 들어 &filter=status%20eq%20'COMPLETED'를 적용하면 완료된 문서 목록을 불러옵니다.

2. 문서 리스트 조회 필터

문서 리스트 조회(GET /documents)에서 사용할 수 있는 필터입니다.

문서 상태

특정 상태의 문서를 조회합니다. eq로 값을 지정하며, 필터에 사용할 수 있는 상태 값은 아래 6가지입니다.

문서 제목

contains를 사용해 제목에 해당 값이 포함된 문서를 조회합니다.

생성일 · 요청일 · 최근 활동일

특정 시간 구간에 생성(createdAt)·요청(startedAt)되었거나, 마지막 활동일이 변경(updatedAt)된 문서를 조회합니다.

ge와 le를 and로 함께 사용하면 기간(between)처럼 조회할 수 있습니다.

createdAt ge '2026-09-01T00:00:00+09:00' and createdAt le '2026-09-30T23:59:59+09:00'

라벨

특정 라벨이 적용된 문서를 조회합니다. in은 전달된 라벨 ID들을 OR 조건으로 검색하며, 라벨 검색은 동시에 최대 20개까지 허용됩니다. 라벨 ID는 라벨 목록 조회 API로 확인할 수 있습니다.

여러 조건 조합

각 조건절 사이에 and를 넣어 함께 사용할 수 있습니다.

status eq 'COMPLETED' and contains(title, '2021')

인코딩 결과는 아래와 같습니다. 줄바꿈 없이 한 줄로 전달하세요.

status%20eq%20'COMPLETED'%20and%20contains(title%2C%20'2021')

3. 템플릿 리스트 조회 필터

템플릿 리스트 조회(GET /templates)는 제목 필터만 지원합니다.

예를 들어 &filter=contains(title%2C%20'2021')를 적용하면 "2021"이 제목에 포함된 템플릿을 불러옵니다.

curl --get 'https://api.modusign.co.kr/templates' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic {인코딩된 API-KEY}' \
  --data-urlencode 'offset=0' \
  --data-urlencode 'limit=10' \
  --data-urlencode "filter=contains(title, '용역')"

4. 자주 쓰는 필터 예시

curl --get 'https://api.modusign.co.kr/documents' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic {인코딩된 API-KEY}' \
  --data-urlencode 'offset=0' \
  --data-urlencode 'limit=100' \
  --data-urlencode "filter=status eq 'COMPLETED' and createdAt ge '2026-09-01T00:00:00+09:00' and createdAt le '2026-09-30T23:59:59+09:00'"

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' \
  --data-urlencode "filter=status eq 'ON_GOING' and contains(title, '근로계약')"

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' \
  --data-urlencode "filter=labelIds in ('{라벨 ID 1}', '{라벨 ID 2}')"

5. 자주 묻는 질문