Zum Hauptinhalt springen
最終更新日: 2025年10月8日

Run in Postman

 HubSpotでは、顧客からのサポートリクエストのことをチケットと呼びます。チケットは、パイプラインステータスでサポートプロセスを通して、クローズされるまで追跡されます。チケットエンドポイントを使用することにより、チケットレコードを作成および管理したり、HubSpotと他のシステムの間でチケットデータを同期したりできます。 オブジェクト、レコード、プロパティー、および関連付けAPIの詳細については、CRMについてのガイドをご確認ください。HubSpotのオブジェクトとレコードに関する一般的な情報については、CRMデータベースを管理する方法をご確認ください。

​
チケットを作成する

新しいチケットを作成するには、POSTリクエストを/crm/v3/objects/ticketsに送信します。 リクエスト内のプロパティーオブジェクトにチケットデータを含めます。また、 関連付けオブジェクトを追加して、新しいチケットを既存のレコード（コンタクト、会社など）やアクティビティー（ミーティング、メモなど）に関連付けることもできます。

​
プロパティー

チケットの詳細は、チケットプロパティーに保存されます。HubSpotの既定のチケットプロパティーがありますが、カスタムプロパティーを作成することもできます。 新しいチケットを作成する際は、subject（チケット名）およびhs_pipeline_stage（チケットのステータス）の各プロパティーをリクエストに含める必要があります。また、複数のパイプラインがある場合はhs_pipelineも含めます。パイプラインが指定されていない場合は、既定のパイプラインが使用されます。 利用可能な全てのプロパティーを確認するには、GETリクエストを/crm/v3/properties/ticketsに送信して、アカウントのチケットプロパティーのリストを取得します。詳しくはプロパティーAPIをご参照ください。
注：APIを介してチケットを作成するときには、チケットステータスまたはパイプラインの内部IDを使用する必要があります。内部IDは数値であり、APIを介してチケットを取得するときにこれも返されます。チケットステータスまたはパイプラインの内部IDは、チケットパイプライン設定で確認できます。
例えば、新しいチケットを作成する場合、リクエストの内容は次のようになります。
  • JSON
///Example request body
{
"properties": {
"hs_pipeline": "0",
"hs_pipeline_stage": "1",
"hs_ticket_priority": "HIGH",
"subject": "troubleshoot report"
}
}

​
関連付け

新しいチケットを作成する際に、関連付けオブジェクトを含めることで、そのチケットを既存のレコードやアクティビティーに関連付けることもできます。例えば、新しいチケットを既存のコンタクトと会社に関連付ける場合、リクエストの内容は次のようになります。
  • JSON
///Example request body
{
"properties": {
"hs_pipeline": "0",
"hs_pipeline_stage": "1",
"hs_ticket_priority": "HIGH",
"subject": "troubleshoot report"
},
"associations": [
{
"to": {
"id": 201
},
"types": [
{
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 16
}
]
},
{
"to": {
"id": 301
},
"types": [
{
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 26
}
]
}
]
}
関連付けオブジェクトには、次のものを含める必要があります。
パラメーター説明
toチケットを関連付けるレコードまたはアクティビティー。一意のid値で指定します。
typesチケットとレコード／アクティビティーの間の関連付けのタイプ。associationCategoryおよびassociationTypeIdを含めます。既定の関連付けタイプIDはこちらのページに記載されています。または、関連付けAPIを使用して、カスタム関連付けタイプ（ラベル）の値を取得することもできます。

​
チケットを取得する

チケットを個別に、または一括で取得できます。
  • 個々のチケットを取得するには、GETリクエストを/crm/v3/objects/tickets/{ticketId}に送信します。
  • 全てのチケットのリストを取得するにはGETリクエストを/crm/v3/objects/ticketsに送信します。
これらのエンドポイントに対し、リクエストのURLに次のクエリーパラメーターを含めることができます。
パラメーター説明
propertiesレスポンスで返されるプロパティーのカンマ区切りのリスト。リクエスト対象のチケットレコードで、指定したプロパティーに値が設定されていない場合、そのプロパティーはレスポンスに含まれません。
propertiesWithHistoryレスポンスで返される現在および過去のプロパティーのカンマ区切りのリスト。リクエスト対象のチケットレコードで、指定したプロパティーに値が設定されていない場合、そのプロパティーはレスポンスに含まれません。
associations関連付けられているIDが取得されるオブジェクトのカンマ区切りのリスト。存在しない関連付けを指定した場合、その関連付けはレスポンスで返されません。詳しくは関連付けAPIをご参照ください。
  • レコードIDまたは一意のカスタム識別子プロパティーを指定して、特定のチケットを一括で取得するには、POSTリクエストをcrm/v3/objects/tickets/batch/readに送信します。このバッチエンドポイントは関連付けを取得できません。詳しくは、関連付けAPIを使用して関連付けを一括読み取りする方法をご参照ください。
一括読み取りエンドポイントの場合は、任意指定のidPropertyパラメーターを使用し、カスタムの固有IDプロパティーを指定して、チケットを取得することもできます。既定で、リクエストのid値はレコードID（hs_object_id）を参照するため、レコードIDを使](/guides/api/crm/properties#固有idプロパティーを作成する)用して取得する場合はidPropertyパラメーターは不要です。固有のカスタム値プロパティーを使用してチケットを取得する場合は、idPropertyパラメーターを含める必要があります。 例えば、チケットを一括で取得する場合のリクエストは、次のいずれかのようになります。 プロパティーの現在の値と過去の値を含むチケットを取得する場合のリクエストは、次のようになります。 
///Example request body with record ID (current and historical values)
{
  "propertiesWithHistory": ["hs_pipeline_stage"],
  "inputs": [
    {
      "id": "4444888856"
    },
    {
      "id": "666699988"
    }
  ]
}

​
チケットを更新する

チケットレコードを個別に、または一括で更新できます。既存のチケットの場合、APIを介してそのチケットを更新するために使用できる固有の既定値は、レコードIDです。ただし、カスタムの固有IDプロパティーを使用してチケットを識別して更新することもできます。
  • レコードIDを指定して個別にチケットを更新するには、更新するデータを含めて、PATCHリクエストを/crm/v3/objects/tickets/{ticketId}に送信します。
  • 複数のチケットを更新するには、POSTリクエストを/crm/v3/objects/tickets/batch/updateに送信します。リクエストの本文に、チケットの識別子と更新するプロパティーを含む配列を含めます。

​
既存のチケットを他のレコードまたはアクティビティーに関連付ける

チケットを他のCRMレコードまたはアクティビティーに関連付けるには、PUTリクエストを/crm/v3/objects/tickets/{ticketId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}に送信します。
associationTypeId値を取得するには、この既定値リストを参照するか、GETリクエストを/crm/v4/associations/{fromObjectType}/{toObjectType}/labelsに送信します。
詳しくは関連付けAPIをご参照ください。

​
関連付けを削除する

チケットレコードと他のレコードまたはアクティビティーの関連付けを削除するには、DELETEリクエストを/crm/v3/objects/tickets/{ticketId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}のURLに送信します。

​
チケットレコードでアクティビティーをピン留めする

リクエストにhs_pinned_engagement_idフィールドを含めると、APIを介してチケットレコードでアクティビティーをピン留めできます。フィールドに、ピン留めするアクティビティーのidを含めます。これは、エンゲージメントAPIを介して取得できます。レコードごとに1つのアクティビティーをピン留めすることができます。ただし、そのアクティビティーはピン留めを行う前にチケットに関連付けられている必要があります。 チケット内のピン留めされたアクティビティーを設定または更新するリクエストは、次のようになります。 
///Example request body PATCH /crm/v3/objects/tickets/{ticketId}
{
  "properties": {
    "hs_pinned_engagement_id": 123456789
  }
}
チケットを作成し、既存のアクティビティーに関連付け、同じリクエストにアクティビティーをピン留めすることもできます。以下で、例をご確認いただけます。 
///Example request body POST /crm/v3/objects/tickets
{
  "properties": {
    "hs_pipeline": "0",
    "hs_pipeline_stage": "1",
    "hs_ticket_priority": "HIGH",
    "subject": "troubleshoot report",
    "hs_pinned_engagement_id": 123456789
  },
  "associations": [
    {
      "to": {
        "id": 123456789
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 227
        }
      ]
    }
  ]
}

​
チケットを削除する

チケットレコードを個別に、または一括で削除できます。削除したチケットレコードは、HubSpot内のごみ箱に追加されます。そのため、必要に応じて後でHubSpot内でチケットを復元できます。 チケットIDを指定して個別にチケットを削除するには、DELETEリクエストを/crm/v3/objects/tickets/{ticketId}に送信します。 チケットの削除の詳細については、 リファレンスドキュメントをご確認ください。