메인 콘텐츠로 건너뛰기

​
개요

이 가이드는 성공적인 가져오기를 위해 CSV 파일을 준비하는 과정을 안내합니다. 오류를 피하려면 다음 단계를 따르세요.

​
1단계: 파일 요구 사항 확인

시작하기 전에 파일이 다음 요구 사항을 충족하는지 확인하세요:
요구 사항세부정보
형식CSV, XLSX 또는 XLS
크기 제한파일당 10,000 레코드
인코딩UTF-8 권장
구조파일당 한 가지 오브젝트 유형
10,000 레코드를 초과하는 데이터세트의 경우, 여러 파일로 분할하거나 API 가져오기를 사용하세요.

​
2단계: 샘플 파일 다운로드

가장 중요한 단계입니다. 샘플 파일은 Twenty가 기대하는 정확한 열 이름과 형식을 보여줍니다.
  1. 오브젝트 보기(사람들, 회사 등)로 이동하세요.
  2. ⋮ → 레코드 가져오기를 클릭하세요
  3. 샘플 파일 다운로드를 클릭하세요
  4. 이 파일을 템플릿으로 사용하세요
전문가 팁: 대신 기존 레코드 몇 개를 내보내세요. 이렇게 하면 데이터가 어떻게 형식화되어야 하는지 실제 예를 얻을 수 있으며, 가져오는 동안 열 이름이 자동으로 매핑됩니다.

​
3단계: 중복 값 제거

Twenty는 일부 필드에 대해 고유성을 적용합니다. 중복 항목은 가져오기 오류를 유발합니다.
객체고유 필드
사람들id, email
회사id, domain
사용자 지정 개체id, 그리고 고유로 표시한 모든 필드
가져오기 전에:
  1. 스프레드시트를 고유 필드(이메일 또는 도메인)로 정렬하세요
  2. 중복 행을 제거하거나 병합하세요
  3. Twenty에 이미 존재하는 중복 항목이 있는지 확인하세요
소프트 삭제된 레코드는 고유성에 포함됩니다. Command Menu → 삭제된 레코드 보기에 있는 레코드는 중복 오류를 일으킵니다. 영구적으로 삭제하거나 복원한 후 업데이트하세요.

​
4단계: 각 필드 유형을 올바르게 형식 지정하기

필드 유형에 따라 요구되는 형식이 다릅니다. 전체 참고 자료는 다음과 같습니다:

​
텍스트 필드

  • 특별한 형식 지정이 필요 없습니다
  • 앞/뒤 공백은 자동으로 제거됩니다

​
이메일 필드

  • 유효한 이메일 형식이어야 합니다: name@domain.com
  • 고유해야 합니다(파일 또는 Twenty에 중복이 없어야 함)
  • 추가 이메일의 경우 Emails / Additional Emails 열에서 다음 형식을 사용하세요:
["jane@twenty.com","jane.doe@twenty.com"]

​
도메인 필드

  • 권장 형식: https://domain.com
  • 이는 메일박스/캘린더 동기화에서 사용하는 형식과 일치하며 중복을 방지합니다
  • 두 열을 모두 채우세요:
    • Domain / Domain Label: domain.com
    • Domain / Domain URL: https://domain.com
  • 파일 내 및 Twenty에서 고유해야 합니다

​
전화번호 필드

전화번호는 여러 열이 필요한 중첩 필드입니다:
열예시
Phones / Primary Phone Number4159095555
Phones / Primary Phone Country CodeUS
Phones / Primary Phone Calling Code+1

​
주소 필드

Address는 여러 열로 구성된 중첩 필드이며(일부는 비워 둘 수 있음):
  • Address / Address 1: 주소 1행
  • Address / Address 2: 주소 2행(선택 사항)
  • Address / City: 도시 이름
  • Address / State: 주 또는 도
  • Address / Country: 국가 이름
  • Address / Post Code: 우편번호/ZIP 코드

​
날짜 필드

파일 전체에서 일관된 형식을 사용하세요:
  • YYYY-MM-DD (권장): 2024-03-15
  • MM/DD/YYYY: 03/15/2024
  • DD/MM/YYYY: 15/03/2024
  • ISO 8601: 2024-03-15T10:30:00Z

​
숫자 필드

  • 숫자만 사용(텍스트 금지)
  • 소수점 구분 기호로 점(.)을 사용: 1234.56
  • 천 단위 구분 기호 사용 금지(1,234.56는 사용하지 마세요)

​
통화 필드

통화는 두 개의 열이 필요한 중첩 필드이며, 두 열 모두 채워야 합니다:
열예시
Amount / Amount1234.56
Amount / CurrencyUSD

​
부울 필드

대문자 사용: TRUE 또는 FALSE
소문자 true 또는 false는 동작하지 않습니다.

​
선택 필드

표시 라벨이 아니라 옵션의 API 이름을 사용하세요. API 이름을 찾는 방법:
  1. 설정 → 데이터 모델로 이동
  2. 객체와 필드를 선택하세요
  3. 고급 모드를 활성화하세요(오른쪽 하단 토글)
  4. API 이름을 복사하세요(예: OPTION_1, “Option 1” 아님)
새 선택 옵션은 자동으로 생성되지 않습니다. 가져오기 전에 설정 → 데이터 모델에서 추가하세요.

​
다중 선택 필드

배열 형식으로 API 이름을 사용: 
[\"VALUE1\",\"VALUE2\"]

​
배열 필드

JSON 배열 형식 사용: 
[\"value1\",\"value2\"]

​
평점 필드

다음 형식을 사용: RATING_1, RATING_2, RATING_3, RATING_4, 또는 RATING_5

​
링크/URL 필드

두 열을 모두 채우세요:
  • Links / Link Label: Twenty
  • Links / Link URL: https://twenty.com
보조 링크의 경우 Links / Secondary Links 열을 사용하세요: 
[{\"url\":\"https://twenty.com\",\"label\":\"Twenty\"}]

​
JSON 필드

유효한 JSON 형식을 사용: 
{\"key\":\"value\",\"key2\":\"value2\"}

​
ID 필드

  • 선택 사항: 제공하지 않으면 Twenty가 ID를 자동 생성합니다
  • 형식: UUID(예: c776ee49-f608-4a77-8cc8-6fe96ae1e43f)
  • 사용 사례: 새로 생성하는 대신 기존 레코드를 업데이트하려면 ID를 포함하세요

​
5단계: 관계 열 추가(레코드를 연결하는 경우)

레코드를 다른 객체에 연결하려면(예: People을 Companies에) 관련 레코드의 고유 식별자가 있는 열을 추가하세요. 예시: People을 Companies에 연결 People CSV에 열을 추가: 
firstName,lastName,email,companyDomain
John,Smith,john@acme.com,https://acme.com
Jane,Doe,jane@widgets.co,https://widgets.co
관계에 대한 중요 규칙:
  • 상위 레코드는 Twenty에 이미 존재해야 합니다
  • 라벨이 아니라 도메인 URL 형식(https://domain.com)을 사용하세요
  • 고유 식별자는 하나만 매핑하세요(companyId와 companyDomain을 모두 포함하지 마세요)
  • 워크스페이스 구성원은 이름이 아닌 이메일을 사용하세요
가져오기 순서가 중요합니다!“one” 측을 “many” 측보다 먼저 가져오세요:
  1. 회사 먼저
  2. 연락처 두 번째(회사 참조 포함)
  3. 기회 세 번째
참조하려면 상위 레코드가 먼저 존재해야 합니다.
자세한 지침은 관계 가져오기 방법을 참조하세요.

​
6단계: Twenty에 필드가 존재하는지 확인

가져오기는 필드가 아니라 레코드를 생성합니다. 가져오려는 모든 필드는 데이터 모델에 이미 존재해야 합니다. 가져오기 전:
  1. 설정 → 데이터 모델로 이동
  2. 객체를 선택하세요
  3. 필요한 사용자 정의 필드를 생성하세요
  4. 필드 이름을 정확히 확인하세요(열 제목과 일치해야 합니다)

​
7단계: 최종 체크리스트

파일을 업로드하기 전에 다음을 확인하세요:
파일 형식이 CSV, XLSX 또는 XLS이어야 합니다
레코드 수가 10,000개 미만이어야 합니다
인코딩이 UTF-8이어야 합니다
이메일(연락처) 또는 도메인(회사)에 중복이 없어야 합니다
날짜 형식이 전체에서 일관되어야 합니다
도메인은 https://domain.com 형식을 사용해야 합니다
부울 필드는 TRUE 또는 FALSE(대문자)를 사용해야 합니다
선택 필드는 표시 라벨이 아닌 API 이름을 사용해야 합니다
모든 사용자 정의 필드가 설정 → 데이터 모델에 존재해야 합니다
상위 레코드를 하위 레코드보다 먼저 가져와야 합니다
관계 열이 기존 레코드를 참조해야 합니다

​
피해야 할 일반적인 실수

실수해결책
TRUE 대신 true 사용부울 값은 대문자여야 합니다
선택 필드에서 표시 라벨 사용설정에서 API 이름을 찾아 사용하세요
회사보다 연락처를 먼저 가져오기항상 상위 객체를 먼저 가져오세요
통화 필드에 통화 코드 누락Amount와 Currency 열을 모두 채우세요
잘못된 도메인 형식https://domain.com 형식을 일관되게 사용하세요
관계에 여러 개의 고유 필드를 매핑함하나만 매핑하세요(도메인 또는 ID, 둘 다는 안 됨)

​
다음 단계

파일이 준비되었습니다! 이제: