Freshdesk API 연락처

Freshdesk API 연락처

Freshdesk에서 연락처(contact)는 지원 티켓을 올린 고객 또는 잠재 고객을 뜻해요. 연락처 API를 쓰면 고객 정보를 만들고, 조회하고, 검색하고, 회사·태그·커스텀 필드와 연결해 관리할 수 있죠. 이 문서에서는 연락처 생성(POST), 조회·검색·필터(GET), 이메일·전화·커스텀 필드 사용법과 응답 형식을 다뤄요. 모든 예시는 https://domain.freshdesk.com을 기준으로 하고, 인증은 -u yourapikey:***처럼 API 키를 써요.

출처: Freshdesk API 문서 - Contacts

본문

연락처는 티켓을 통해 소통하는 고객의 기본 단위예요. API로 CRUD뿐 아니라 검색·필터·내보내기·병합 같은 관리 작업까지 전부 처리할 수 있고, 요청과 응답은 전부 JSON으로 주고받아요. 먼저 연락처를 하나 만들면서 기본 흐름을 잡아볼게요.

연락처 생성 (Create a Contact)

새 연락처를 만들려면 /api/v2/contacts에 POST 요청을 보내요. name은 필수이고, 이메일·전화·모바일·트위터 ID·소셜 핸들·고유 외부 ID 중 하나는 반드시 함께 보내야 해요.

주요 파라미터를 살펴보면 이래요:

속성 타입 설명
name string 연락처 이름 (필수)
email string 기본 이메일 주소 (고유). 추가 이메일은 other_emails로 지정해요
phone string 전화번호
mobile string 휴대폰 번호
twitter_id string 트위터 핸들 (고유)
unique_external_id string 외부 ID (고유)
other_emails array 연락처에 연결할 추가 이메일 목록
company_id number 기본(primary) 소속 회사 ID
view_all_tickets boolean 연락처가 소속 회사의 모든 티켓을 볼 수 있는지
other_companies array 추가로 연결할 회사 목록 (Multiple Companies 기능 활성화 시, Estate 플랜 이상)
address string 주소
avatar object 프로필 이미지. 최대 5MB, .jpg, .jpeg, .jpe, .png 지원
custom_fields dictionary 커스텀 필드의 이름·값 쌍. 날짜 필드는 YYYY-MM-DD 형식만 입력받아요
description string 연락처 설명
job_title string 직함
language string 언어. 기본값은 "en" (Multiple Language 기능 시, Garden 플랜 이상)
tags array 연락처에 붙일 태그
time_zone string 시간대. 기본값은 도메인 시간대 (Multiple Time Zone 기능 시, Garden 플랜 이상)
lookup_parameter string Custom Objects 기능 활성화 시 사용. display_id(레코드 ID) 또는 primary_field_value(사용자 정의 값). 기본값은 display_id

기본적인 생성 요청은 이렇게 써요:

curl -v -u yourapikey:*** -H 'Content-Type: application/json' -X POST -d '{
  "name":"Super Man",
  "email":"[email protected]",
  "other_emails": ["[email protected]", "[email protected]"]
}' 'https://domain.freshdesk.com/api/v2/contacts'

생성에 성공하면 만들어진 연락처 전체를 JSON으로 돌려줘요. 티켓 생성과 달리 200 상태로, 응답 본문에 연락처 객체가 담겨요:

{
  "active": false,
  "address": null,
  "company_id": 23,
  "view_all_tickets": false,
  "deleted": false,
  "description": null,
  "email": "[email protected]",
  "id": 432,
  "contact_type": "contact",
  "job_title": null,
  "language": "en",
  "mobile": null,
  "name": "Super Man",
  "phone": null,
  "time_zone": "Chennai",
  "twitter_id": null,
  "social_handler": [],
  "other_emails": ["[email protected]", "[email protected]"],
  "other_companies": [
    { "company_id": 25, "view_all_tickets": true },
    { "company_id": 26, "view_all_tickets": false }
  ],
  "created_at": "2015-08-28T09:08:16Z",
  "updated_at": "2015-08-28T09:08:16Z",
  "tags": [],
  "avatar": null
}

contact_type 필드는 연락처가 contact인지 visitor인지를 나타내요. 이 값과 social_handler, devices 같은 일부 필드는 2022년 6월 이후 가입했거나 최신 Contacts/Companies로 업그레이드한 계정에서만 사용할 수 있어요.

커스텀 필드와 함께 생성하기 (Custom Object 연동)

연락처를 만들면서 커스텀 객체(custom object) 레코드를 연결할 수도 있어요. lookup_parameter로 primary_field_value를 지정하고, custom_fields에 레코드 값을 넣는 방식이에요.

curl -v -u yourapikey:*** -H 'Content-Type: application/json' -X POST -d '{
  "name":"Super Man",
  "email":"[email protected]",
  "other_emails": ["[email protected]", "[email protected]"],
  "lookup_parameter" : "primary_field_value",
  "custom_fields" : { "order_number" : "12345" }
}' 'https://domain.freshdesk.com/api/v2/contacts'

이때 응답에는 커스텀 필드가 그대로 들어와요:

{
  "active": false,
  "address": null,
  "company_id": 23,
  "view_all_tickets": false,
  "deleted": false,
  "description": null,
  "email": "[email protected]",
  "id": 432,
  "name": "Super Man",
  "custom_fields": {
    "order_number": "12345"
  },
  "created_at": "2015-08-28T09:08:16Z",
  "updated_at": "2015-08-28T09:08:16Z",
  "tags": [],
  "avatar": null
}

여기서 lookup_parameter는 display_id(레코드 ID, 예: _0-1)나 primary_field_value(사용자가 정의한 값, 예: 주문번호 12345) 중 하나를 받아요. 아무 값도 주지 않으면 기본값은 display_id예요.

아바타 포함 생성 (multipart/form-data)

아바타 이미지를 함께 올리려면 Content-Type을 multipart/form-data로 바꿔야 해요. 파일과 필드를 -F로 함께 보내요:

curl -v -u yourapikey:*** -F 'avatar=@/path/to/image.ext' -F 'name=Green Lantern' -F '[email protected]' -X POST 'https://domain.freshdesk.com/api/v2/contacts'

응답의 avatar 객체에는 파일 정보가 담겨요:

{
  "active": false,
  "email": "[email protected]",
  "id": 434,
  "name": "Green Lantern",
  "avatar": {
    "avatar_url": "",
    "content_type": "application/octet-stream",
    "id": 4,
    "name": "lantern.png",
    "size": 13036,
    "created_at": "2015-08-28T10:27:58Z",
    "updated_at": "2015-08-28T10:27:58Z"
  }
}

연락처 조회 (View / List)

하나 조회는 /api/v2/contacts/[id]에 GET을 보내요. 연락처 정보와 함께 custom_fields, devices까지 함께 돌아와요:

curl -v -u yourapikey:*** -H 'Content-Type: application/json' -X GET 'https://domain.freshdesk.com/api/v2/contacts/434'

{
  "active": false,
  "address": null,
  "company_id": 23,
  "view_all_tickets": false,
  "description": null,
  "email": "[email protected]",
  "id": 434,
  "name": "Green Lantern",
  "custom_fields": {
    "department": "Operations",
    "fb_profile": null,
    "permanent": false
  },
  "tags": [],
  "avatar": {
    "avatar_url": "",
    "content_type": "application/octet-stream",
    "id": 4,
    "name": "rails.png",
    "size": 13036,
    "created_at": "2015-08-28T10:27:58Z",
    "updated_at": "2015-08-28T10:27:58Z"
  },
  "devices": [
    {
      "device_type": "web",
      "device_make": "Apple",
      "device_model": "Chrome",
      "app_version": "1.0.4",
      "os": "Mac OS",
      "os_version": "10.15.7"
    }
  ]
}

전체 목록은 같은 /api/v2/contacts에 GET을 보내요. 기본적으로 차단(blocked)되지 않고 삭제되지 않은 모든 연락처를 가나다순으로 돌려주고, 필터를 조합해 원하는 연락처만 골라낼 수도 있어요. 필터를 쓸 때는 쿼리 문자열을 URL 인코딩해야 한다는 점만 기억해요.

필터 사용법
이메일·모바일·전화 [email protected], ?mobile=7654367287, ?phone=4352789885
회사 ?company_id=45653
상태 ?state=[blocked/deleted/unverified/verified]
연락처 유형 ?contact_type=[contact/visitor]
갱신 시점 ?updated_since=2018-01-19T02:00:00Z

예를 들어 이메일은 고유하므로 하나의 연락처만 나오고, 검증된 연락처를 20개만 가져오거나 특정 시점 이후 갱신된 연락처를 보려면 이렇게 써요:

curl -v -u yourapikey:*** -X GET 'https://domain.freshdesk.com/api/v2/[email protected]'
curl -v -u yourapikey:*** -X GET 'https://domain.freshdesk.com/api/v2/contacts?state=verified&per_page=20'
curl -v -u yourapikey:*** -X GET 'https://domain.freshdesk.com/api/v2/contacts?updated_since=2018-01-19T02:00:00Z'

전체 목록 응답은 연락처 객체들의 배열이에요:

[
  {
    "active": false,
    "address": null,
    "company_id": null,
    "description": null,
    "email": "[email protected]",
    "id": 2,
    "contact_type": "contact",
    "job_title": null,
    "language": "en",
    "mobile": null,
    "name": "Rachel",
    "phone": null,
    "time_zone": "Chennai",
    "twitter_id": null,
    "social_handler": [],
    "created_at": "2015-08-18T16:18:14Z",
    "updated_at": "2015-08-24T09:25:19Z",
    "custom_fields": {
      "department": "Admin",
      "fb_profile": null,
      "permanent": true
    }
  }
]

연락처 검색 (Search Contacts)

이름으로 연락처를 찾으려면 /api/v2/contacts/autocomplete?term=[keyword]에 GET을 보내요. 검색은 대소문자를 구분하지 않지만, 부분 문자열(substring) 검색은 지원하지 않아요. 예를 들어 "John Jonz"라는 연락처는 john, Joh, Jonz, jon으로는 찾을 수 있지만 hn이나 nz로는 검색되지 않아요.

curl -v -u yourapikey:*** -X GET 'https://domain.freshdesk.com/api/v2/contacts/autocomplete?term=John'

응답은 id와 name만 담은 배열이에요:

[
  { "id": 33, "name": "John Jonz" },
  { "id": 456, "name": "John Steven Jonz" }
]

연락처 필터 (Filter Contacts, BETA)

커스텀 필드를 기준으로 연락처를 필터링하려면 /api/v2/search/contacts?query=[query]를 써요. List All Contacts의 단순 필터가 특정 기본 속성만 지원한다면, 이 검색 엔드포인트는 계정에서 만든 커스텀 필드를 포함한 다양한 조건을 조합할 수 있어요.

쿼리 형식은 "(contact_field:integer OR contact_field:'string') AND contact_field:boolean" 같은 꼴이에요. 몇 가지 규칙이 있는데요:

  • 삭제된 연락처는 결과에 포함되지 않아요.
  • 쿼리는 URL 인코딩해야 하고, 큰따옴표로 감싸야 하며 최대 512자까지 쓸 수 있어요.
  • AND, OR 같은 논리 연산자와 괄호 ()로 조건을 그룹화할 수 있어요.
  • 날짜·숫자 필드에는 >=(:>)와 <=(:<) 같은 관계 연산자를 쓸 수 있어요.
  • 날짜 필드 입력은 UTC 형식이에요.
  • 페이지당 30개까지 반환되고, 전체 결과 수(total)도 함께 돌려줘요. 페이지는 page 파라미터로 넘기는데 1부터 시작해 10을 넘지 못해요.
  • 값이 없는 필드를 걸러내려면 null 키워드를 써요.
  • 업데이트 후 검색에 반영되기까지 몇 분이 걸릴 수 있어요.

검색 쿼리는 대소문자를 구분하니 커스텀 필드 이름을 Contact Fields 엔드포인트에서 정확히 확인한 뒤 쓰는 게 좋아요.

curl -v -u yourapikey:*** -X GET 'https://domain.freshdesk.com/api/v2/search/contacts?query="active:true"'

응답은 전체 개수와 결과 목록으로 나뉘어요:

{
  "total": 22,
  "results": [
    {
      "active": true,
      "address": "11 Park Avenue,",
      "company_id": 331,
      "description": "alien hero",
      "email": "[email protected]",
      "id": 112,
      "job_title": "Superhero",
      "contact_type": "contact",
      "language": "en",
      "mobile": "992339928",
      "name": "John Jonz",
      "phone": "+199****2882",
      "time_zone": "Eastern Time (US & Canada)",
      "twitter_id": "martian",
      "social_handler": [],
      "custom_fields": {
        "location": "Watch tower",
        "sector": "outer space"
      },
      "created_at": "2017-07-19T12:29:36Z",
      "updated_at": "2017-07-19T12:38:26Z"
    }
  ]
}

예를 들어 회사 2331에 속한 검증된 사용자를 찾으려면 이렇게 조합해요:

curl -v -u yourapikey:*** -X GET 'https://domain.freshdesk.com/api/v2/search/contacts?query="active:true%20AND%20company_id:2331"'

이메일·전화·태그처럼 글자 값을 필터링할 때는 작은따옴표로 감싸요(예: tag:'VIP'). 지원되는 기본 필드는 active, company_id, twitter_id, email, phone, mobile, tag, language, time_zone, created_at, updated_at이에요. 커스텀 필드는 Single line text(string), Number(integer), Checkbox(boolean), Dropdown(string)을 걸러낼 수 있죠.

이메일 · 전화 · 커스텀 필드 정리

연락처를 다룰 때 가장 자주 쓰는 값 세 가지를 짚어볼게요.

  • 이메일: email이 기본 이메일이고 고유해요. 이메일이 여러 개면 other_emails 배열에 추가하는데, 생성·조회·병합 어디에서나 같은 원칙이에요. 연락처를 하나 조회하면 응답에 email과 other_emails가 각각 들어 있어요.
  • 전화: phone(전화)과 mobile(휴대폰)을 별도 속성으로 관리해요. 전체 목록 조회에서 이메일·모바일·전화 필터로 각각 걸러낼 수 있고, 검색(Filter) 엔드포인트에서도 phone:·mobile: 쿼리로 필터링해요.
  • 커스텀 필드: custom_fields 딕셔너리에 이름·값 쌍으로 담아요. 생성·수정 시 함께 보낼 수 있고, 조회 응답에도 그대로 포함돼요. Filter(BETA) 엔드포인트에서 커스텀 필드 값으로 연락처를 골라낼 수 있다는 게 핵심이에요. 날짜 커스텀 필드만 YYYY-MM-DD 형식 입력을 요구해요.

더 알아보기 (Learn more)