요청자 / 서명자 입력란 구분하기

개요

모두싸인 서비스에서 템플릿 편집 시, 문서 위에는 각기 다른 색의 입력란을 볼 수 있습니다. 모두 "입력란"이라 비슷해 보이지만, 누구의 값을 채우는지에 따라 완전히 다릅니다. 이 차이를 모르면 원하는 데이터를 엉뚱한 파라미터에 넣어 서명 요청이 실패할 수 있습니다.

요청자 입력란 (회색)

서명을 요청하는 사람(요청자)이 문서를 보내기 전에 미리 채워 넣는 값입니다. 계약 금액, 안내 문구처럼 요청자가 이미 알고 있는 정보에 사용합니다. API에서는 requesterInputs에 해당합니다.

서명자 입력란 (노란색)

문서를 받은 참여자(서명자·열람자)가 서명 과정에서 직접 입력하거나 서명하는 값입니다. 서명란, 참여자 이름, 동의 체크박스 등에 사용합니다. API에서는 participants[].fields에 해당합니다.

예시와 같이, 서명자가 1명이 있는 경우에는 요청자의 텍스트는 회색, 서명자의 텍스트는 노란색으로 확인하실 수 있습니다.

📘
용어 참고
모두싸인 웹 화면에서는 "요청자 입력란 / 서명자 입력란"으로 부르고, API 문서에서는 "요청자 입력(requesterInputs) / 참여자 필드(participants[].fields)"로 부릅니다. 이 문서에서는 화면 용어(입력란)를 기준으로 설명합니다.

한눈에 보는 차이

구분	요청자 입력란	서명자 입력란
값 입력 주체	요청자 (문서를 보내는 사람)	참여자 (서명자·열람자)
입력 시점	서명 요청 발송 전	서명 진행 중
참여자별 구분	없음 (문서당 요청자는 1명)	있음 (서명자를 1명 이상 추가할 수 있음)
템플릿 상세 조회 응답 위치	`requesterInputs`	`participants[].fields`
서명 요청 시 값 지정 파라미터	`document.requesterInputMappings`	`document.participantMappings[].fieldMappings`
대표 예시	계약 금액, 계약 조항, 안내 문구	서명란, 참여자 이름, 주소, 동의 체크박스

⚠️
가장 흔한 실수
requesterInputMappings에 서명자 입력란의 데이터 라벨을 넣거나, 반대로 fieldMappings에 요청자 입력란의 데이터 라벨을 넣는 경우입니다. 두 파라미터는 서로의 데이터 라벨을 인식하지 못해 요청이 실패합니다. 자세한 증상과 해결은 아래 FAQ를 참고하세요.

활용 시나리오

본 문서를 참고하여, 아래의 상황에서 적용해볼 수 있습니다. 문서를 읽기 전 먼저 생각해두고 이해하시면 도움이 됩니다.

근로계약서 — 금액은 요청자가, 이름·서명은 근로자가

계약 금액처럼 회사가 이미 아는 값은 요청자 입력란(requesterInputMappings)으로 미리 채워 보내고, 근로자 이름·서명은 서명자 입력란(fieldMappings)으로 두어 근로자가 직접 입력·서명하게 합니다.

동의서 — 안내 문구는 회색, 동의 체크는 노란색

안내 문구·약관 요약은 요청자 입력란(TEXT)으로 미리 넣고, 동의 여부 체크박스는 서명자 입력란(CHECKBOX)으로 두어 참여자가 직접 체크하도록 합니다.

이름만 미리 채워 보내기

참여자 이름을 미리 알고 있어 편의상 채워 두고 싶다면, 서명자 입력란(TEXT 타입)에 prefilledValue로 이름을 넣습니다. 단, NAME 타입 입력란은 미리 채울 수 없습니다.

적용 API

엔드포인트	메서드	설명
`/documents/request-with-template`	`POST`	템플릿으로 서명 요청
`/templates/{templateId}`	`GET`	템플릿 정보 가져오기

두 입력란의 데이터 라벨은 템플릿에 미리 설정되어 있습니다. 서명 요청을 보낼 때는 이 데이터 라벨에 값을 "매칭"하는 방식이라, 연동 전에 먼저 템플릿의 데이터 라벨을 확인하는 것을 권장합니다.

1단계 — 내 템플릿의 데이터 라벨 확인하기

GET /templates/{templateId}를 호출하면, 요청자 입력란과 서명자 입력란이 각각 어떤 데이터 라벨(dataLabel)로 설정되어 있는지 확인할 수 있습니다. 두 입력란은 응답에서 서로 다른 위치에 담겨 옵니다.

{
  "id": "TEMPLATE_ID",
  "title": "근로계약서",
  "requesterInputs": [
    {
      "type": "TEXT",
      "dataLabel": "계약금액",
      "value": "5,000,000원"
    }
  ],
  "participants": [
    {
      "type": "SIGNER",
      "role": "근로자",
      "fields": [
        {
          "type": "SIGNATURE",
          "dataLabel": "근로자 서명",
          "required": true
        },
        {
          "type": "TEXT",
          "dataLabel": "근로자 이름",
          "required": true
        }
      ]
    }
  ]
}

요청자 입력란 → 최상위 requesterInputs 배열
서명자 입력란 → participants[].fields 배열 (참여자 역할 role별로 나뉘어 있음)

2단계 — 요청자 입력란에 값 채우기

문서 전체에 한 번 적용되는 값이므로, document.requesterInputMappings에 데이터 라벨과 값을 지정합니다.

파라미터	타입	필수	설명
`dataLabel`	string	✓	템플릿의 요청자 입력란 데이터 라벨 (1~100자)
`value`	string \| boolean \| object	✓	채울 값. 타입별로 형식이 다릅니다(아래 참고)

value에 넣는 형식은 입력란 타입에 따라 다릅니다.

입력란 타입	`value` 형식	예시
`TEXT`	문자열 (최대 1,000자)	`"5,000,000원"`
`CHECKBOX`	`boolean`	`true`
`IMAGE`	`{ "base64": "..." }` (3MB 이하 jpg/png)	`{ "base64": "iVBORw0..." }`

{
  "templateId": "TEMPLATE_ID",
  "document": {
    "title": "견적서",
    "requesterInputMappings": [
      {
        "dataLabel": "계약금액",
        "value": "5,000,000원"
      }
    ]
  }
}

< 텍스트, 체크박스, 이미지는 API 활용 가능 / 드롭다운, 요청자 이름 은 API 불가 >

📘
API로 값을 넣을 수 있는 타입은 3종입니다
템플릿에서는 요청자 입력란을 텍스트·체크박스·이미지·드롭다운·요청자 이름으로 만들 수 있지만, requesterInputMappings로 값을 주입할 수 있는 타입은 TEXT, CHECKBOX, IMAGE 3종입니다. 드롭다운·요청자 이름 입력란의 값은 API로 요청이 불가하니, 해당 부분의 수정은 모두싸인 웹 앱에서 진행해주세요.

3단계 — 서명자 입력란에 값 미리 채우기

참여자별로 적용되는 값이므로, 값을 채울 참여자의 role 아래 fieldMappings에 지정합니다. 만일 이미 템플릿에 기본 텍스트가 적용되어 있었다면, 덮어쓰기로 처리됩니다.

파라미터	타입	필수	설명
`dataLabel`	string	✓	템플릿의 서명자 입력란 데이터 라벨
`excluded`	boolean	✓	해당 입력란을 이번 서명 요청에서 제외할지 여부. `true`이면 서명자 입력란으로 적용되지 않습니다. 자세한 활용은 아래 참고
`prefilledValue`	string \| boolean \| object \| null		미리 채울 값. 타입별로 형식이 다릅니다(아래 참고)

prefilledValue에 넣는 형식은 서명자 입력란 타입에 따라 다릅니다.

입력란 타입	`prefilledValue` 형식	예시
`TEXT`, `COMPANY_NAME`	문자열	`"홍길동"`
`CHECKBOX`	`boolean`	`true`
`DATE`	ISO 8601 날짜 문자열	`"2026-03-01"`
`DROPDOWN`	선택할 옵션 값 문자열	`"매니저"`
`ADDRESS`	`{ address1, address2, city, province, zip, country }` 객체	`{ "address1": "...", "zip": "06133", ... }`

여러 타입의 서명자 입력란에 값을 한 번에 미리 채우는 예시입니다.

{
  "templateId": "TEMPLATE_ID",
  "document": {
    "title": "2026_근로계약서_홍길동",
    "participantMappings": [
      {
        "role": "근로자",
        "name": "홍길동",
        "signingMethod": {
          "type": "EMAIL",
          "value": "[email protected]"
        },
        "fieldMappings": [
          {
            "dataLabel": "근로자 이름",
            "excluded": false,
            "prefilledValue": "홍길동"
          },
          {
            "dataLabel": "계약 시작일",
            "excluded": false,
            "prefilledValue": "2026-03-01"
          },
          {
            "dataLabel": "재택근무 동의",
            "excluded": false,
            "prefilledValue": true
          },
          {
            "dataLabel": "직급",
            "excluded": false,
            "prefilledValue": "매니저"
          },
          {
            "dataLabel": "주소",
            "excluded": false,
            "prefilledValue": {
              "address1": "서울특별시 강남구 테헤란로 1",
              "address2": "10층",
              "city": "강남구",
              "province": "서울특별시",
              "zip": "06133",
              "country": "KR"
            }
          }
        ]
      }
    ]
  }
}

⚠️
미리 채울 수 없는 타입도 있습니다
서명(SIGNATURE), 이름(NAME), 이미지(IMAGE), 서명일(SIGNING_DATE) 입력란은 서명자가 직접 입력·서명해야 하므로 prefilledValue로 미리 채울 수 없습니다.

`excluded` — 서명자별로 입력란을 켜고 끄기

excluded는 템플릿에는 입력란을 만들어 두되, 이번 서명 요청에서는 특정 참여자에게 그 입력란을 받을지 말지를 결정하는 값입니다. 하나의 템플릿을 여러 상황에 재사용할 때 유용합니다.

excluded: false (기본값) — 해당 입력란을 그대로 사용합니다. 값을 미리 채우려면 prefilledValue를 함께 넣습니다.
excluded: true — 해당 입력란을 이번 요청에서 제외합니다. 그 참여자에게는 이 입력란이 나타나지 않습니다.

예를 들어 템플릿에 "계좌번호" 입력란을 만들어 두고, 직원 A에게는 계좌번호를 받고 직원 B에게는 받지 않으려는 경우, 참여자별로 아래와 같이 다르게 지정할 수 있습니다.

{
  "templateId": "TEMPLATE_ID",
  "document": {
    "title": "정산 동의서",
    "participantMappings": [
      {
        "role": "직원A",
        "name": "홍길동",
        "signingMethod": {
          "type": "EMAIL",
          "value": "[email protected]"
        },
        "fieldMappings": [
          {
            "dataLabel": "계좌번호",
            "excluded": false
          }
        ]
      },
      {
        "role": "직원B",
        "name": "김모두",
        "signingMethod": {
          "type": "EMAIL",
          "value": "[email protected]"
        },
        "fieldMappings": [
          {
            "dataLabel": "계좌번호",
            "excluded": true
          }
        ]
      }
    ]
  }
}

위 예시에서 직원 A에게는 계좌번호 입력란이 그대로 노출되고, 직원 B에게는 계좌번호 입력란이 제외되어 나타나지 않습니다.

🚧
excluded는 생략하지 마세요
fieldMappings에서는 dataLabel과 excluded가 모두 필수 값입니다. 값을 미리 채우기만 할 때는 excluded: false와 prefilledValue를 함께 넣어 주세요. 입력란을 제외할 때는 excluded: true만 넣으면 되며, 이때 prefilledValue는 무시됩니다.

전체 요청 예시

하나의 서명 요청에서 요청자 입력란과 서명자 입력란에 값을 함께 지정하는 예시입니다. 두 입력란은 서로 다른 파라미터에 나눠서 넣습니다.

{
  "templateId": "TEMPLATE_ID",
  "document": {
    "title": "2026_근로계약서_홍길동",
    "participantMappings": [
      {
        "role": "근로자",
        "name": "홍길동",
        "signingMethod": {
          "type": "EMAIL",
          "value": "[email protected]"
        },
        "fieldMappings": [
          {
            "dataLabel": "근로자 이름",
            "excluded": false,
            "prefilledValue": "홍길동"
          }
        ]
      }
    ],
    "requesterInputMappings": [
      {
        "dataLabel": "계약금액",
        "value": "5,000,000원"
      }
    ]
  }
}

📘
두 입력란은 한 파라미터로 함께 보낼 수 없습니다
요청자 입력란은 document.requesterInputMappings로, 서명자 입력란은 document.participantMappings[].fieldMappings로 각각 나눠서 지정해야 합니다.

주의사항

⚠️
requesterEditable가 false인 템플릿
템플릿의 requesterEditable 값이 false이면, 기본 발송 설정을 제외한 서명자 입력란 데이터를 수정해서 발송할 수 없습니다. 이 경우 fieldMappings로 값을 덮어쓰려고 하면 의도대로 적용되지 않을 수 있으니, 템플릿 상세 조회 응답에서 requesterEditable 값을 먼저 확인하세요.

FAQ

422 Data label of requester input is not matched 오류가 발생합니다.

requesterInputMappings에 넣은 dataLabel이 템플릿의 요청자 입력란에 존재하지 않을 때 발생합니다.

응답 예시:

{
  "statusCode": 422,
  "message": "Data label of requester input is not matched"
}

다음 항목을 확인해 보세요.

템플릿 상세 조회로 requesterInputs에 실제로 있는 dataLabel을 확인하세요.
requesterInputMappings에는 요청자 입력란의 dataLabel만 넣었는지 확인하세요.
dataLabel의 대소문자·공백·특수문자가 템플릿과 정확히 일치하는지 확인하세요.

422 Cannot map to signer field 오류가 발생합니다. (가장 흔한 실수)

서명자 입력란에 넣어야 할 값을 요청자 입력란(requesterInputMappings)에 잘못 넣었을 때 발생합니다.

응답 예시:

{
  "statusCode": 422,
  "message": "Cannot map to signer field"
}

서명자 입력란 값은 requesterInputMappings가 아니라, 해당 참여자(role)의 participantMappings[].fieldMappings로 넣어야 합니다. 두 입력란의 dataLabel을 서로 바꿔 넣지 않았는지 확인하세요.

422 Requester input value is invalid 오류가 발생합니다.

요청자 입력란의 value가 입력란 타입과 맞지 않을 때 발생합니다.

응답 예시:

{
  "statusCode": 422,
  "message": "Requester input value is invalid"
}

TEXT 타입에는 문자열 값을 넣으세요.
CHECKBOX 타입에는 불리언(true/false) 값을 넣으세요.

422 Participant role is not matched 오류가 발생합니다.

participantMappings의 role이 템플릿에 정의된 참여자 역할과 일치하지 않을 때 발생합니다. 템플릿 상세 조회 응답의 participants[].role 값과 정확히 일치하는지 확인하세요.

요청자 입력란과 서명자 입력란을 한 파라미터로 함께 보낼 수 있나요?

아니요. 값을 지정하는 파라미터 자체가 다릅니다. 요청자 입력란은 document.requesterInputMappings로, 서명자 입력란은 document.participantMappings[].fieldMappings로 각각 나눠서 지정해야 합니다.

드롭다운·요청자 이름 요청자 입력란도 API로 값을 넣을 수 있나요?

아니요. requesterInputMappings로 값을 주입할 수 있는 요청자 입력란 타입은 TEXT, CHECKBOX, IMAGE 3종입니다. 드롭다운·요청자 이름 입력란의 값은 템플릿에 설정된 값을 그대로 사용하세요.

템플릿을 만들 때 회색/노란색 입력란을 나중에 바꿀 수 있나요?

입력란의 색상만 바꾸는 기능은 없습니다. 요청자 입력란과 서명자 입력란은 성격이 다른 별개의 입력란이므로, 템플릿 편집 화면에서 원하는 종류의 입력란으로 다시 만들어야 합니다.

👍
더 자세한 API 내용은 API References에서 확인하세요!
템플릿으로 서명 요청 · 템플릿 정보 가져오기 API의 자세한 내용을 확인하세요.

요청자 / 서명자 입력란 구분하기

개요

용어 참고

한눈에 보는 차이

가장 흔한 실수

활용 시나리오

적용 API

1단계 — 내 템플릿의 데이터 라벨 확인하기

2단계 — 요청자 입력란에 값 채우기

API로 값을 넣을 수 있는 타입은 3종입니다

3단계 — 서명자 입력란에 값 미리 채우기

미리 채울 수 없는 타입도 있습니다

`excluded` — 서명자별로 입력란을 켜고 끄기

`excluded`는 생략하지 마세요

전체 요청 예시

두 입력란은 한 파라미터로 함께 보낼 수 없습니다

주의사항

`requesterEditable`가 `false`인 템플릿

FAQ

더 자세한 API 내용은 API References에서 확인하세요!

개요

용어 참고

한눈에 보는 차이

가장 흔한 실수

활용 시나리오

적용 API

1단계 — 내 템플릿의 데이터 라벨 확인하기

2단계 — 요청자 입력란에 값 채우기

API로 값을 넣을 수 있는 타입은 3종입니다

3단계 — 서명자 입력란에 값 미리 채우기

미리 채울 수 없는 타입도 있습니다

excluded — 서명자별로 입력란을 켜고 끄기

excluded는 생략하지 마세요

전체 요청 예시

두 입력란은 한 파라미터로 함께 보낼 수 없습니다

주의사항

requesterEditable가 false인 템플릿

FAQ

더 자세한 API 내용은 API References에서 확인하세요!

`excluded` — 서명자별로 입력란을 켜고 끄기

`excluded`는 생략하지 마세요

`requesterEditable`가 `false`인 템플릿