YappliCRMでは、標準の項目（氏名やランクなど）以外に、顧客（会員）ごとに独自の項目を追加できる「カスタムフィールド」（column01〜column50）を利用できます。会員の誕生日や好みのカテゴリなど、YappliCRMの標準項目にない情報を管理したい場合に使う仕組みで、外部システム連携でもよく利用されます。設計上の注意点をまとめます。
件数と型
カスタムフィールドは column01〜column50 の最大50個 まで利用できます。50個という上限はシステム上の制約のため、これ以上増やすことはできません。
各カスタムフィールドには、YappliCRMの管理画面上で「文字列」「数値」「日付」「日付時間」のいずれかの型を設定できます。ただし、この型設定は登録・更新時の入力チェックにのみ使われ、保存・返却される値は常にString型です。レスポンスの column01〜column50 は、管理画面上の型設定にかかわらず、常に文字列として返却されます。
型ごとの入力チェックの挙動は以下のとおりです。
| 型設定 | 入力チェック | 保存・返却される値の例 |
|---|---|---|
| 文字列 | 制限なし | 入力した文字列のまま |
| 数値 | 数値として解釈できる値のみ許可（123 / 000123 / -5 / 12.5 等）。数値として解釈できない値（abc 等）はエラー（column01には、数字を指定してください。） |
入力した文字列のまま（例：000123 → "000123"。先頭の 0 等も保持されます） |
| 日付 | Y-m-d（例：2000-01-01）形式のみ許可。それ以外の形式はエラー（column01の形式は、'Y-m-d'と合いません。） |
ハイフンを除去した8桁の文字列（例：2000-01-01 → "20000101"） |
| 日付時間 | Y-m-d H:i（秒なし。例：2000-01-01 12:34）形式のみ許可。秒を含む形式（Y-m-d H:i:s）を含め、それ以外の形式はエラー（column01の形式は、'Y-m-d H:i'と合いません。） |
ハイフン・スペース・コロンを除去した12桁の文字列（例：2000-01-01 12:34 → "200001011234"） |
日付・日付時間型のフィールドは、取得したレスポンスの値（"20000101"等）をそのまま更新APIに渡すとエラーになります。更新時はY-m-d/Y-m-d H:i形式に変換してから送信してください。
空文字（""）は、いずれの型でも入力チェックを素通りしますが、システム側でnullとして扱われ、nullで保存されます（レスポンスも""ではなくnullで返却されます）。そのため、更新APIで空文字を送信すると、その項目の既存の値がクリアされます。値を変更したくない項目は、キーごとリクエストに含めないようにしてください。
各カスタムフィールドあたり数百文字程度（半角文字、全角文字）に収める運用を推奨します。
with_column_key パラメータ
カスタムフィールドを物理名（キー名）で取得したい場合、with_column_key パラメータを使用できます。
| エンドポイント | with_column_key |
|---|---|
顧客一覧 (GET /api/ext/users) |
利用不可。常に連番キー（column01〜）で返却されます |
顧客詳細 (GET /api/ext/users/{id}) |
利用可能（デフォルト false） |
| 顧客詳細（ユニークID） | 利用可能（デフォルト false） |
| 顧客詳細（外部連携ID） | 利用可能（デフォルト false） |
顧客登録・更新 (POST / PUT) |
利用可能（デフォルト false） |
顧客一覧APIで物理名を取得したい場合は、一覧で取得したIDを使って顧客詳細APIを個別に呼び出す設計としてください。
external_key / external_ids（外部連携ID）
外部連携ID（external_ids）は、外部システム独自のIDをYappliCRMの顧客に紐づけられる機能です。カスタムフィールドとの違いは、値のユニーク性を保証できる点と、そのIDをもとにした顧客参照が高速な点です。
external_key の設定方法
external_key（外部連携IDのキー名）は、クライアント側で直接設定することはできません。設定が必要な場合は、当社担当者までご連絡ください。設定されたキー名は、以降OpenAPIの顧客登録・更新のフィールド名として利用可能になり、顧客一覧・詳細取得APIのレスポンスにもそのキーの値が含まれるようになります。
制約
- 登録できるキーは 最大5件 まで
- キー名は 最大64文字、英数字と
_-の記号のみ 使用可能 - キー名は 一度登録すると編集できません（誤って設定した場合は削除して新規登録し直してください）
- キーを削除すると、そのキーに紐づいていた全顧客の値も削除されます（他のキーの値は残ります）
顧客登録・更新時に、設定されていない external_key を指定した場合はエラーにならず、そのキーだけ無視されます（登録・更新自体は成功します）。意図したキー名で登録できているか、事前にご確認ください。
external_ids の値の制約
- キーを指定する場合、値は必須（空文字列・
nullは不可） - 文字列のみ（配列等は不可）
- 最大255文字
- 使用可能な記号は
*-._（URLエンコードが不要な記号のみ許可） - 同一クライアント内で、同一キーの値は重複できません
補足
external_ids はOpenAPI経由での利用に特化した機能で、CSVには対応していません。
- CSVには出力されません。顧客情報のCSVエクスポートファイルに
external_idsの値は含まれません。 - CSVでの登録・更新はできません。CSVインポートによる顧客情報の登録・更新では、
external_idsを設定・変更することはできません。 - 管理画面の顧客詳細画面では確認できます。YappliCRMの管理画面で個々の顧客の詳細画面を開くと、
external_idsの値を確認できます。なお、顧客一覧APIのレスポンスにはexternal_idsは含まれません。
カスタムフィールド更新時のトリガー発火について
PUT /api/ext/users/{id} でカスタムフィールドの値を更新すると、YappliCRM側で設定されている「指定カラム変化トリガー」が発火する場合があります。これは、特定のカラムの値が変化した際にアプリ内施策（プッシュ通知やポイント付与など）を自動実行する仕組みです。
外部システム側から意図せず大量のカスタムフィールド更新をおこなうと、意図しないタイミングでアプリ内施策が起動する可能性があるため、トリガー設定がある環境と連携する際は、更新のタイミング・頻度に注意してください。