GoHighLevelのカスタムフィールドを日本語の名前で作ると2本目から400——fieldKeyの指定で直す

GoHighLevelのカスタムフィールドを、Claude CodeからAPIで一気に作る場面があります。顧客の属性や案件の項目を、日本語の名前のまま何十本も用意したいときです。

私たちは、2026年7月23日にデモ用の検証アカウントで29本のフィールドを作ったときに、この作業で最初に止まりました。この記事では、止まった症状と原因、そして外し方をお伝えします。確かめたのは、カスタムフィールドを作るAPI（POST /locations/{loc}/customFields）の範囲です。

症状は、1本目だけ通って2本目から400になること

最初の1本は、何事もなく作れます。画面にも日本語の名前で出ます。ところが2本目を同じ要領で作ると、400が返ります。内容は「同じキーのフィールドがすでにある」という衝突です。

名前は別のものを付けています。なのに衝突するので、最初は原因の見当がつきません。3本目以降も、すべて同じ400で止まります。

原因は、キーを自動で作る処理で日本語の文字が除外されるように見えたこと

GoHighLevelは、フィールドのキーを、渡した名前から自動で作ります。私たちの検証アカウントでは、この処理においてASCII以外の文字が除外されるように見えました。

私たちの検証アカウントでカスタムフィールドを作成したときは、次のように見えました。名前が英数字を含んでいれば残った文字がキーになり、名前が日本語だけだと残る文字がゼロになるように見えます。その結果、キーが空のスラッグになり、どのフィールドも同じ空のキーになっているように見受けられます。

1本目は、空のキーがまだ使われていないので通ります。2本目からは、空のキーがすでに使われているため、衝突するように見えました。名前の違いは、キーに反映されていないように見えます。

fieldKeyの名前の決まりの例（私たちの運用ルール）

キーを自動生成に任せず、手動で指定するときは、キーの付け方をあらかじめ決めておくと安心です。

私たちは、fieldKeyを半角の英小文字、数字、下線（アンダースコア）だけで書く運用にしています。これはGoHighLevelの一般仕様として確かめた結果ではなく、私たちが採用している命名ルールです。大文字やスペース、日本語の文字を入れるとエラーになるのかどうかは、この記事で確認できた検証範囲には含めていません。公式の現行ページでもご確認ください。

具体的な命名の例としては、以下のような形式が挙げられます。

• 例：company_scale（企業の規模を表す場合）
• 例：preferred_contact_time（連絡希望時間を表す場合）
• 例：membership_rank（会員ランクを表す場合）

このように、単語の間を下線で繋ぐことで、プログラムから読み取りやすく重複のないキーを安全に設計することができます。

作成前のチェック表

APIリクエストを実際に実行する前に、送信予定のデータ構造に誤りがないかをあらかじめ確認するためのチェックリストを用意しておくと、手戻りを防ぐことができます。事前の検証を丁寧に行うことが、一括作成を成功させるための秘訣です。

以下の項目を順番に確認し、すべての条件を満たしていることを確かめてからスクリプトを実行してください。

• 作成するすべてのカスタムフィールドの表示名（name）が日本語で分かりやすく設定されているか
• fieldKeyが、私たちの運用ルール（英小文字・数字・下線だけ）に沿っているか
• dataTypeの指定が、テキスト、数値、日付などのデータ型と正しく一致しているか
• modelの指定がコンタクト用またはオポチュニティ用のどちらを指しているか明確になっているか

これらの項目をしっかりと確認することで、システム側のバリデーションエラーを未然に防ぎ、スムーズに処理を進めることができます。同じ相手に月次のカードを積み上げる、オポチュニティの重複解禁とステージ順の指定も参考にしながら、全体の構造を確認しておきましょう。

直し方は、fieldKeyを明示すること

作成のリクエストに、fieldKeyを自分で渡します。名前は日本語のままで構いません。表示名と、内部のキーは別のものだからです。

私たちが2026年7月23日にデモ用の検証アカウントで試したときの、リクエストの形は次のとおりです。

• name：画面に出る名前。日本語でよい
• fieldKey：内部のキー。私たちは英小文字と数字と下線だけで書く
• dataType：項目の型。テキスト、数値、日付など
• model：コンタクト用かオポチュニティ用か

接頭辞は付けない

私たちの検証アカウントで見た範囲では、作られたキーには、コンタクト用なら先頭に contact. が、オポチュニティ用なら opportunity. が自動で付くように見えました。公式の現行ページでもご確認ください。fieldKeyに最初から付けて渡したときに接頭辞が二重になるかどうかは、この記事で確認できた検証範囲には含めていません。そのため私たちは、fieldKeyには接頭辞より後ろの部分だけを渡す運用にしています。

表示名は日本語のままでよい

実際に試した例では、名前を「受給者証番号」、fieldKeyを sk_jukyushasho_bango としました。画面には「受給者証番号」と出て、キーは contact.sk_jukyushasho_bango になりました。「利用開始日」を start_date で作る形は、仕組みを説明するための例で、実測の出典があるものではありません。

日本語の名前を英語に直す必要はありません。画面を使う人には日本語が見え、APIを使うClaude Codeには英語のキーが見えます。どちらも困りません。

実測では、29本を衝突ゼロで作れた

私たちは、2026年7月23日にデモ用の検証アカウントで、カスタムフィールドを作るAPI（POST /locations/{loc}/customFields）にfieldKeyを明示して、コンタクト用17本とオポチュニティ用12本を、続けて作りました。結果は次のとおりです。

• 衝突は0件
• 作成後に一覧（GET）を読み出して、29本の実在を確認
• 画面の名前は、すべて日本語のまま

fieldKeyに共通の接頭辞を付けておくと、あとで便利でした。検証用のフィールドだけを一覧から選び出すとき、キーの先頭で絞り込めるからです。私たちは、検証用に専用の接頭辞を決め、消すときもその接頭辞で探しています。

作成後に一覧でキーの空欄を確かめる手順

APIリクエストが正常に完了したように見えても、内部で予期せぬ挙動が発生している場合があります。そのため、作成処理が終わった直後に、データの一覧を改めて取得して中身を自分の目で確かめる手順を踏むことが大切です。

確認を行う際は、APIを通じて保存されたカスタムフィールドの一覧データを取得し、それぞれのレコードのキー項目を確認します。もしキーの欄が空欄になっていたり、意図しない文字列になっていたりするものがあれば、その時点で正しく反映されていないことが分かります。

具体的な確かめのポイントは次のとおりです。

• 新しく作成した分のIDの集合と照合して、正しく作られているか確かめる
• すべてのカスタムフィールドにおいて、fieldKeyに値が正しく入っているか確認する
• 日本語の表示名が画面上のレイアウトや各項目で正しく表示されているか確かめる

この確認作業をルーティン化することで、万が一の登録漏れやパラメータの渡し間違いに素早く気づくことができます。GoHighLevelのタスクは更新で欄が消える。全項目を送り、完了は値で読むの内容も踏まえつつ、正確な値の読み取りを心がけてください。

カスタム値の扱いでも、同様の状況が見られた

2026年7月16日の別のデモ検証で、カスタム値（Custom Values）を扱ったときも、同様の状況が見られました。これはカスタムフィールドの検証とは別の実測です。なお、カスタムオブジェクトのフィールドでfieldKeyの明示が同じように効くかは、まだ確かめていません。名前が日本語だけだと、キーが空のスラッグになり、2本目から「同じキーがすでにある」という400が返るように見えました。

直し方は、フィールドとは少し違います。カスタム値には、fieldKeyを渡す欄がありません。代わりに、名前の中にASCIIの語を入れます。たとえば「発行元の名称 issuer_name」のように、日本語の名前の後ろに英語の語を添えます。すると、その英語の語がキーになります。

もう一つ、知っておきたいことがあります。すでに作ってしまったカスタム値の名前を、あとから直しても、キーは作り直されません。名前の変更では、壊れたキーは直らないのです。直すには、削除して、英語の語を添えた名前で作り直します。カスタム値を削除して作り直すときは、そのフィールドを使っているテンプレートやワークフローに影響しないか先に確かめてください。

よくある質問（名前を直せばキーも直るか）

カスタムフィールドやカスタム値の運用に関して、現場でよく寄せられる疑問の一つに、表示名を後から変更すれば内部のキーも自動的に修正されるのではないかという点があります。

表示名と内部のキーは別のものなので、表示名を後から変えても、すでに作られたキーが変わるとは限りません。名前を変える前に、取得した一覧でキーを確かめ、これから作る分は fieldKey を明示して作ります。AIの引き継ぎをGHLのノートに残す。カードIDが実はコンタクトIDだった罠の状況にも注意しながら、適切なデータ管理を行いましょう。

Claude Codeに作らせるときの指示

Claude Codeに作成を頼むときは、最初の指示に次の3点を入れておくと、止まりにくくなります。

• 名前は日本語、fieldKeyは英小文字の下線つなぎで、1本ごとに別の値を決める
• 私たちが試した範囲では、fieldKeyに contact. や opportunity. を付けない
• 作成後に新しく作成した分のIDの集合で照合して確かめる

3点目は、見落としやすい点です。作成のリクエストが成功したように見えても、キーが空で作られていることがあるからです。今回作ったIDの一覧と照らし、キーが空のものがないかも見ます。

次に読む

カスタムフィールドを作ったら、次はそこに値を入れる側を整えます。オポチュニティを同じ相手に何件も積み上げる設定は、オポチュニティの重複を解禁する記事にまとめました。