ピープルAPIドキュメンテーション

メソッド

入力

エンドポイントのURL 

https://v1/peoplemgmt/v1.0/people

このエンドポイントURLでは、

• personapi.gainsightcloud.comがGainsightに接続できるドメインです。あくまで参考です
• ピープルは 、個人オブジェクトモデルのレコードを挿入または更新することを表します。

リクエスト本文のサンプル

会社や関係の関連付けがない新しい個人レコードを個人オブジェクトに挿入できます。リクエスト本文で個人オブジェクトに挿入したいレコードを渡します。オブジェクト内のフィールドとそれに関連付けられた値は、以下に示す様にキーと値のペアとして渡されます。挿入する必要があるレコードを配列項目として渡します。

注意:

• 個人のメールを渡すことは必須であり、それは個人オブジェクト内の既存レコードを解決するための一意の制約として使用されます。
• 個人オブジェクトの既存レコードとメールが一致するレコードを渡すと、既存レコードの残りのフィールドが他の詳細で更新されます。

{
  "FirstName": "John",
  "LastName": "Smith",
  "Email": "jsmith@abc.com"
}

パラメーター

以下は、個人、会社個人、および関係個人オブジェクトのパラメーターです。

成功レスポンスのサンプル

APIリクエストが成功すると、レスポンスとしてHTTPステータスコード200が返されます。レスポンス形式は以下の通りです。レスポンスに成功すると、個人オブジェクトからの新しいレコードの一意のGSIDが含まれます。

{
  "result": true,
  "requestId": "ffad9762-4b55-424f-b9d4-f7c5f634752b",
  "data": {
    "record": {
      "emailoptout": false,
      "createdby": "1P013MQAG8HNIY3NZ4AAA11VYQ2OHJ94A9H",
      "email": "t@t.com",
      "createddate": "2022-10-31T05:38:32.034",
      "modifiedby": "1P013MQAG8HNIY3NZAA11VYQ2OHJ94A9H",
      "name": "abc",
      "gsid": "1P0452MXO8N9COP0OCGAAAJCA7X3ZVEZ",
      "modifieddate": "2022-10-31T05:44:19.862",
      "companies": [
        {
          "person_id": {
            "Id": "1P0452MXO8N9COP0OAAIQY7JCA7X3ZVEZ",
            "name": "abc"
          },
          "company_id": {
            "Id": "1P02URY3JWNYZJWFIAAA2XA7VS0IO49MIO",
            "name": "unilever"
          },
          "modifiedby": "1P013MQAG8HNIY3NZAAAU11VYQ2OHJ94A9H",
          "createdby": "1P013MQAG8HNIY3AAAG4U11VYQ2OHJ94A9H",
          "createddate": "2022-10-31T05:38:32.74",
          "active": true,
          "modifieddate": "2022-10-31T05:38:32.74",
          "gsid": "1C013F7LHUKCPMTLKZAAAAMIDM501AD23NCX"
        }
      ]
    }
  }
}

失敗レスポンスのサンプル

{
  "result": false,
  "requestId": "831b395b-9467-43f4-a912-7ca21d6e761f",
  "data": {
    "error": {
      "details": [
        {
          "errors": [
            {
              "message": "Upsert Keys '[Email]' values empty or null",
              "code": "GSOBJ_VCR1008"
            }
          ]
        }
      ]
    }
  }
}

メソッド

入力

エンドポイントのURL

https://personapi.gainsightcloud.com/v1/peoplemgmt/v1.0/people

このエンドポイントURLでは、

• personapi.gainsightcloud.comがGainsightに接続できるドメインです。あくまで参考です
• ピープルは 、個人オブジェクトモデルのレコードを挿入または更新することを表します。

リクエスト本文のサンプル

リクエスト本文の個人、会社個人、関係個人オブジェクトに挿入したいレコードを渡します。オブジェクトのフィールドとそれに関連する値は、以下のようにキーと値のペアとして渡されます。挿入する必要があるレコードを配列項目として渡します。会社の個人オブジェクトと関係オブジェクトにレコードを挿入する際に、メールを一意の制約として個人オブジェクトからGSIDを取得し、提供された詳細情報で個人オブジェクトの他のフィールドを更新します。

個人オブジェクトで利用できない個人レコードのメールをAPIで渡すと、個人オブジェクトに新規レコードが作成されます。  個人オブジェクトの既存レコードとメールが一致するレコードを渡した場合、既存レコードの残りのフィールドが他の詳細で更新されます。同様に、メール/個人IDおよび関係ID/関係ルックアップの詳細を一意の制約として使用し、個人および関係個人の既存レコードを更新することができます。

{
    "FirstName": "John",
    "LastName": "Smith",
    "Email": "jsmith@abc.com",
    "companies": [
        {
            "Company_ID":"1I00V4ALRX6A6ZOEQ0FNJ3CXSRAVFFWJCCCA",
            "IsPrimaryCompany": "false"
        },
        {
            "Company_ID":"2J33V5ALRX6A6ZOEQ0FNJ3CXSRAVFFWJBBBD",
            "IsPrimaryCompany": "true",
            "relationships": [
                {
                  "Role": "Admin",
                  "IsPrimaryCompany": "true",
                  "Relationship_ID": "1I00V4ALRX6A6ZOEQ0FNJ3CXSRAVFFWJAAA2"

        }
        ]
    }
  ] 
}

{
  "FirstName": "John",
  "LastName": "Smith",
  "Email": "jsmith@abc.com",
  "companies": [
    {
      "CompanyName": "Drivedata",
      "IsPrimaryCompany": "false",
      "role": "Power User",
      "CustomObject__column1": 9234567891
    },
    {
      "CompanyName": "abc, Inc.",
      "IsPrimaryCompany": "true",
      "Relationships": [
        {
          "role": "Admin",
          "IsPrimaryCompany": "true",
          "RelationshipName": "Asia Pacific"
        }
      ]
    }
  ],
  "lookups": {
    "companies": {
      "Company_ID": {
        "fields": {
          "CompanyName": "Name"
        },
        "lookupField": "Gsid",
        "objectName": "Company",
        "multiMatchOption": "FIRSTMATCH",
        "onNoMatch": "ERROR"
      },
      "Deskphone__gc": {
        "fields": {
          "CustomObject__column1": "Phone_num_custom_column"
        },
        "lookupField": "Gsid",
        "objectName": "custom_table_name",
        "multiMatchOption": "FIRSTMATCH",
        "onNoMatch": "ERROR"
      }
    },
    "relationships": {
      "Relationship_ID": {
        "fields": {
          "RelationshipName": "Name"
        },
        "lookupField": "Gsid",
        "objectName": "Relationship",
        "multiMatchOption": "FIRSTMATCH",
        "onNoMatch": "ERROR"
      }
    }
  }
}

{
  "lookups": {
    "companies": {
      "Company_ID": {
        "fields": {
          "CompanyName": "Name"
        },
        "lookupField": "Gsid",
        "objectName": "Company",
        "multiMatchOption": "FIRSTMATCH",
        "onNoMatch": "ERROR"
      },
      "Deskphone__gc": {
        "fields": {
          "CustomObject__column1": "Phone_num_custom_column"
        },
        "lookupField": "Gsid",
        "objectName": "custom_table_name",
        "multiMatchOption": "FIRSTMATCH",
        "onNoMatch": "ERROR"
      }
    },
    "relationships": {
      "Relationship_ID": {
        "fields": {
          "RelationshipName": "Name"
        },
        "lookupField": "Gsid",
        "objectName": "Relationship",
        "multiMatchOption": "FIRSTMATCH",
        "onNoMatch": "ERROR"
      }
    }
  }
}

{
  "FirstName": "John",
  "LastName": "Smith",
  "Name": "John Smith",
  "Email": "jsmith@abc.com",
  "relationships": [
    {
      "Role": "Admin",
      "IsPrimaryCompany": "true",
      "RelationshipName": "Asia Pacific"
    }
  ],
  "lookups": {
    "relationships": {
      "Relationship_ID": {
        "fields": {
          "RelationshipName": "Name"
        }
      }
    }
  }
}

パラメーター

以下は、個人、会社個人、および関係個人オブジェクトのパラメーターです。

成功レスポンスのサンプル

APIリクエストが成功すると、レスポンスとしてHTTPステータスコード200が返されます。レスポンス形式は以下の通りです。レスポンスに成功すると、個人オブジェクトからのレコードの一意のGSIDが含まれます。

{
  "result": true,
  "requestId": "30f39fc7-2ba8-4684-92b5-d2292992ef1c",
  "data": {
    "record": {
      "firstname": "John",
      "emailoptout": false,
      "createdby": "1P013MQAG8HNIY3NZ41G4U11VYQ2OHJ94A9H",
      "email": "jsmith@abc.com",
      "createddate": "2022-10-31T05:52:55.927",
      "modifiedby": "1P013MQAG8HNIY3NZ41G4U11VYQ2OHJ94A9H",
      "name": "John Smith",
      "lastname": "Smith",
      "gsid": "1P0452MXO8N9COP0OCMY6OOCSJ4J9JOD1GSG",
      "modifieddate": "2022-10-31T05:56:29.582",
      "companies": [
        {
          "person_id": {
            "Id": "1P0452MXO8N9COP0OCMY6OOCSJ4J9JOD1GSG",
            "name": "John Smith"
          },
          "isprimarycompany": false,
          "modifiedby": "1P013MQAG8HNIY3NZ41G4U11VYQ2OHJ94A9H",
          "createdby": "1P013MQAG8HNIY3NZ41G4U11VYQ2OHJ94A9H",
          "createddate": "2022-10-31T05:52:55.986",
          "active": true,
          "modifieddate": "2022-10-31T05:54:57.894",
          "gsid": "1C013F7LHUKCPMTLKZ7SC9H259O4GFEA44ZO"
        },
        {
          "person_id": {
            "Id": "1P0452MXO8N9COP0OCMY6OOCSJ4J9JOD1GSG",
            "name": "John Smith"
          },
          "isprimarycompany": true,
          "modifiedby": "1P013MQAG8HNIY3NZ41G4U11VYQ2OHJ94A9H",
          "createdby": "1P013MQAG8HNIY3NZ41G4U11VYQ2OHJ94A9H",
          "createddate": "2022-10-31T05:52:56.042",
          "active": true,
          "modifieddate": "2022-10-31T05:54:57.941",
          "gsid": "1C013F7LHUKCPMTLKZM9H1VLD7WLAJMEGECB",
          "relationships": [
            {
              "modifiedby": "1P013MQAG8HNIY3NZ41G4U11VYQ2OHJ94A9H",
              "person_id": {
                "Id": "1P0452MXO8N9COP0OCMY6OOCSJ4J9JOD1GSG",
                "name": "John Smith"
              },
              "active": true,
              "role": "1I0054U9FAKXZ0H26H8UXDA0ZVKNQ2SWMBER",
              "isprimarycompany": true,
              "createdby": "1P013MQAG8HNIY3NZ41G4U11VYQ2OHJ94A9H",
              "modifieddate": "2022-10-31T05:54:57.989",
              "gsid": "1C03MYKI9D09MW4JRS9QV0A70LBF62UTM8SA",
              "createddate": "2022-10-31T05:52:56.148",
              "company_person_id": "1C013F7LHUKCPMTLKZM9H1VLD7WLAJMEGECB"
            }
          ]
        }
      ]
    }
  }
}

失敗レスポンスのサンプル

{
  "result": false,
  "requestId": "e8ad4c82-689b-4ec3-b2e7-87cac173a210",
  "data": {
    "error": {
      "details": [
        {
          "errors": [
            {
              "message": "Upsert Keys '[Email]' values empty or null",
              "code": "GSOBJ_VCR1008"
            }
          ]
        }
      ]
    }
  }
}

メソッド

入力

エンドポイントのURL

https://personapi.gainsightcloud.com/v1/peoplemgmt/v1.0/people

このエンドポイントURLでは、

• personapi.gainsightcloud.comがGainsightに接続できるドメインです。あくまで参考です
• ピープルは 、個人、関係個人オブジェクトのレコードを挿入または更新することを表します。

リクエスト本文のサンプル

個人ID、会社ID、関係IDのみで、会社個人、関係個人オブジェクトに挿入したいレコードを渡します。

1人の個人が複数の会社と関連することができます。「会社」および「関係」のフィールドデータは、それぞれ会社および関係関連レコードのリストを表します。APIリクエスト本文で提供されるインポートルックアップの設定を使用して、会社IDと関係IDを取得できます。会社ID、個人ID、関係IDを取得するには、

• APIで渡された個人の詳細を紐付けるために、「ルックアップ詳細」を使って個人オブジェクトのメールフィールドと一致し、個人オブジェクトのレコードを特定するのに役立つキー・値ペアとして、「メール」を渡します。
• 「会社」フィールドで、 「ルックアップ詳細」を使用して会社オブジェクトのフィールドと一致するのに役立つキー・値ペアを渡し、会社オブジェクトからGSIDを取得してターゲットフィールド会社IDに入力します。「会社ID」フィールドで検索条件を渡すと、「ルックアップ」フィールドで提供されるルックアップ設定と連動し、会社オブジェクトから検索条件と一致するレコードの会社ID（GSID）を取得します。
• 同様に、インポートルックアップ設定を使用して、関係個人オブジェクトに関係IDを取得することができます。GSIDタイプフィールドの値を読み込むためのインポートルックアップ設定の詳細については、インポートルックアップセクションをご参照ください。
• また、インポートルックアップ設定を使用して、GSIDデータタイプの任意のカスタムフィールドに値を入力できます。
• lookupField、objectName、multiMatchOption、onNoMatchなどのルックアップの詳細を渡すことは、GSIDを個人ID、会社ID、関係IDなどの標準フィールドに入力するために必須ではありません。GSIDデータタイプのカスタムフィールドに渡す必要があります。
• ルックアップの詳細を渡さない場合、そのシステムは「multiMatchOption」」のデフォルトオプションを考慮します：「FIRSTMATCH」および「onNoMatch」「ERROR」。

個人オブジェクトおよび会社個人オブジェクトの既存のレコードと一致するレコード、メールおよび会社IDを渡すと、既存のレコードの残りのフィールドが他の詳細で更新されます。同様に、新しいレコードのメールと関係IDが、個人と関係個人オブジェクトの既存のレコードと一致すると、既存のレコードの残りのフィールドが他の詳細で更新されます。

以下は、アップサートAPIのサンプルとルックアップの詳細です:

• 「会社」 フィールドでは、「CompanyName」と「PersonEmail」がルックアップの設定と連動して、会社IDと個人IDフィールドに値を取得します。同様に、「RelationshipName」は、ルックアップの詳細を使用して関係Dに値を取得するために提供されます。
• 「ルックアップ」フィールドには、会社オブジェクトおよび関係オブジェクトの「会社名」、「関係名」フィールドで指定された名前を検索し、会社IDおよび関係IDを取得するように設定されています。同様に、渡されたメールは個人オブジェクトのメールと一致し、既存の個人IDを会社個人および関係個人オブジェクトに取得します。GSIDタイプフィールドの値を読み込むためのインポートルックアップ設定の詳細については、インポートルックアップセクションをご参照ください。

サンプルAPI：

{
  "companies": [
    {
      "CompanyName": "abc, Inc.",
      "PersonEmail": "jsmith@abc.com",
      "IsPrimaryCompany": "true",
      "relationships": [
        {
          "Role": "Admin",
          "IsPrimaryCompany": "true",
          "RelationshipName": "Asia Pacific"
        }
      ]
    }
  ],
  "lookups": {
    "companies": {
      "Company_ID": {
        "fields": {
          "CompanyName": "Name"
        }
      },
      "Person_ID": {
        "fields": {
          "PersonEmail": "Email"
        }
      }
    },
    "relationships": {
      "Relationship_ID": {
        "fields": {
          "RelationshipName": "Name"
        }
      }
    }
  }
}

パラメーター

以下は、個人、会社個人、および関係個人オブジェクトのパラメーターです。

成功レスポンスのサンプル

APIリクエストが成功すると、レスポンスとしてHTTPステータスコード200が返されます。レスポンス形式は以下の通りです。レスポンスに成功すると、個人オブジェクトからのレコードの一意のGSIDが含まれます。

{
    "result": true,
    "requestId": "093e78ca-47a0-4512-bd0f-01ea58e944ef",
    "data": {
        "status": "SUCCESS",
        "personGsid": "1P04QNK6ENCURXXDZW5XK6PQMFFDEBD8EL3K"
    }
}

失敗レスポンスのサンプル

APIリクエストがエラーになった場合、次の形式でエラーレスポンスが返されます。エラー応答には、Gainsightエラーコードとエラーの説明が含まれています。GainsightのエラーコードとHTTPステータスコードの応答は、様々な理由で発生する可能性があります。Gainsightのエラーコードの全リスト、エラーの説明、その理由、HTTPステータスコードについては、「その他のリソース」セクションにある「個人API のエラーコード」の記事をご参照ください。

以下のエラーレスポンス本文では、エラーの説明として、指定された会社IDのルックアップ検索条件で、一致するレコードが会社オブジェクトに見つからないという、このAPIの失敗理由を示しています。

{
    "result": false,
    "requestId": "27b8df50-beed-48c8-9b00-c5aebf9a1bcc",
    "data": {
        "status": "FAILURE",
        "errors": [
            {
                "field": "Company_ID",
                "invalidValue": [
                    {
                      "Email": "abc, Inc.",
                      "Company_ID": "RLS_SOURCE_LOOKUP_FIELD_NOT_RESOLVED"
                    }
                ],
                "errorCode": "RLS_SOURCE_LOOKUP_FIELD_NOT_RESOLVED",
                "errorMessage": "ResolveLookupService source lookup field not resolved"
            }
        ]
    }
}

メソッド

入力

エンドポイントのURL

https://personapi.gainsightcloud.com/v1/peoplemgmt/v1.0/people/async

このエンドポイントURLでは、

• personapi.gainsightcloud.comがGainsightに接続できるドメインです。あくまで参考です。
• ピープル: 個人オブジェクトのレコードを挿入または更新することを表します。
• 非同期: 1回のAPIコールで複数の個人レコードを挿入または更新するためのメソッドを表します。

リクエスト本文のサンプル

会社や関係の関連付けがない新しい個人レコードは、個人オブジェクトに挿入できます。リクエスト本文でオブジェクトに挿入または更新したいレコードを渡します。オブジェクト内のフィールドとそれに関連付けられた値は、以下に示す様にキーと値のペアとして渡されます。  各レコードを配列項目として渡します。1回のAPIコールで最大50件のレコードが更新できます。オブジェクト内の全てのデータ型のフィールドは、メソッドを通じて更新することができます。

注意:

• 個人のメールを渡すことは必須であり、それは個人オブジェクト内の既存レコードを解決するための一意の制約として使用されます。
• 個人オブジェクトの既存レコードとメールが一致するレコードを渡すと、既存レコードの残りのフィールドが他の詳細で更新されます。
• レコードの挿入や更新が完了するまでには、最大で30分かかります。

{
  "records": [
    {
      "Name": "John Smith",
      "FirstName": "John",
      "LastName": "Smith",
      "Email": "jsmith@abc.com"
    },
    {
      "Name": "Steven Ferguson",
      "FirstName": "Steven",
      "LastName": "Ferguson",
      "Email": "sferguson@drivedata.com"
    },
    {
      "Name": "Amanda Churchill",
      "FirstName": "Amanda",
      "LastName": "Churchill",
      "Email": "achurchill@simplify.com"
    }
  ]
}

パラメーター

以下は、個人、会社個人、および関係個人オブジェクトのパラメーターです。

成功レスポンスのサンプル

APIリクエストは、「データ」にステータスIＤを含むレスポンスとして、HTTPステータスコード200を返します。レスポンス形式は以下の通りです。以下のレスポンスでは、データ「キー」a679fc3e-2ae6-48c1-95b6-ed82f9b8619e の値が ステータスIDになっています。アップサートステータスAPIのエンドポイントURLでこの ステータスIＤを渡すと、個人レコードの一括データアップサートのステータスを取得できます。

{
    "result": true,
    "requestId": "7581e498-c37e-4057-8fc9-c8d4d543de1a",
    "data": {
        "statusId": "e3f66752-bd71-4826-b9e0-892f7c0a841e"
    }
}

メソッド

入力

エンドポイントのURL

https://personapi.gainsightcloud.com/v1/peoplemgmt/v1.0/people/async

このエンドポイントURLでは、

• personapi.gainsightcloud.comがGainsightに接続できるドメインです。あくまで参考です。
• ピープルは 、個人オブジェクトモデルのレコードを挿入または更新することを表します。
• 非同期: 1回のAPIコールで複数の個人レコードを挿入または更新するためのメソッドを表します。

リクエスト本文のサンプル

リクエスト本文の個人、会社個人、関係個人オブジェクトに挿入したいレコードを渡します。オブジェクトのフィールドとそれに関連する値は、以下のようにキーと値のペアとして渡されます。挿入する必要があるレコードを配列項目として渡します。1回のAPIコールで最大50件の個人レコードがアップサートできます。

レコードを個人オブジェクトにアップサートする際に、メールを一意の制約として使用して個人オブジェクトからGSIDを取得し、個人オブジェクトの他のフィールドを指定された詳細で更新します。個人オブジェクトで利用できない個人レコードのメールを渡すと、個人オブジェクトに新規レコードが作成されます。個人および会社個人の既存レコードに一致するレコード、メール/個人ID、および会社ID/会社ルックアップIDを渡した場合、既存レコードの残りのフィールドは他の詳細で更新されます。同様に、メール/個人IDおよび関係ID/関係ルックアップの詳細を一意の制約として使用し、個人および関係個人の既存レコードを更新することができます。

{
  "records": [
    {
      "Name": "John Smith",
      "FirstName": "John",
      "LastName": "Smith",
      "Email": "jsmith@abc.com",
      "companies": [
        {
          "Company_ID": "7581e498-c37e-4057-8fc9-c8d4d543de1a",
          "IsPrimaryCompany": "true",
          "relationships": [
            {
              "Role": "Admin",
              "IsPrimaryCompany": "true",
              "Relationship_ID": "7581e498-c37e-4057-8fc9-c8d4d543bbbb"
            }
          ]
        }
      ]
    },
    {
      "Name": "Steven Ferguson",
      "FirstName": "Steven",
      "LastName": "Ferguson",
      "Email": "sferguson@drivedata.com",
      "companies": [
        {
          "Company_ID": "7581e498-c37e-4057-8fc9-c8d4d543de1a",
          "IsPrimaryCompany": "true",
          "relationships": [
            {
              "Role": "Executive Sponsor",
              "IsPrimaryCompany": "true",
              "Relationship_ID": "7581e498-c37e-4057-8fc9-c8d4d543bbbb"
            }
          ]
        }
      ]
    },
    {
      "Name": "Amanda Churchill",
      "FirstName": "Amanda",
      "LastName": "Churchill",
      "Email": "achurchill@simplify.com",
      "companies": [
        {
          "Company_ID": "7581e498-c37e-4057-8fc9-c8d4d543de1a",
          "IsPrimaryCompany": "true",
          "relationships": [
            {
              "Role": "Decision Maker",
              "IsPrimaryCompany": "true",
              "Relationship_ID": "7581e498-c37e-4057-8fc9-c8d4d543bbbb"
            }
          ]
        }
      ]
    }
  ]
}

{
  "records": [
    {
      "Name": "John Smith",
      "FirstName": "John",
      "LastName": "Smith",
      "Email": "jsmith@abc.com",
      "companies": [
        {
          "CompanyName": "abc, Inc.",
          "IsPrimaryCompany": "true",
          "relationships": [
            {
              "Role": "Admin",
              "IsPrimaryCompany": "true",
              "RelationshipName": "Asia Pacific"
            }
          ]
        }
      ],
      "lookups": {
        "companies": {
          "Company_ID": {
            "fields": {
              "CompanyName": "Name"
            }
          }
        },
        "relationships": {
          "Relationship_ID": {
            "fields": {
              "RelationshipName": "Name"
            }
          }
        }
      }
    },
    {
      "Name": "Steven Ferguson",
      "FirstName": "Steven",
      "LastName": "Ferguson",
      "Email": "sferguson@drivedata.com",
      "companies": [
        {
          "CompanyName": "Drive Data",
          "IsPrimaryCompany": "true",
          "relationships": [
            {
              "Role": "Executive Sponsor",
              "IsPrimaryCompany": "true",
              "RelationshipName": "South Central"
            }
          ]
        }
      ],
      "lookups": {
        "companies": {
          "Company_ID": {
            "fields": {
              "CompanyName": "Name"
            }
          }
        },
        "relationships": {
          "Relationship_ID": {
            "fields": {
              "RelationshipName": "Name"
            }
          }
        }
      }
    },
    {
      "Name": "Amanda Churchill",
      "FirstName": "Amanda",
      "LastName": "Churchill",
      "Email": "achurchill@simplify.com",
      "companies": [
        {
          "CompanyName": "Simplify, Inc.",
          "IsPrimaryCompany": "true",
          "relationships": [
            {
              "Role": "Decision Maker",
              "IsPrimaryCompany": "true",
              "RelationshipName": "Middle East"
            }
          ]
        }
      ],
      "lookups": {
        "companies": {
          "Company_ID": {
            "fields": {
              "CompanyName": "Name"
            }
          }
        },
        "relationships": {
          "Relationship_ID": {
            "fields": {
              "RelationshipName": "Name"
            }
          }
        }
      }
    }
  ]
}

パラメーター

以下は、個人、会社個人、および関係個人オブジェクトのパラメーターです。

成功レスポンスのサンプル

APIリクエストは、「データ」にステータスIＤを含むレスポンスとして、HTTPステータスコード200を返します。レスポンス形式は以下の通りです。以下のレスポンスでは、データ「キー」a679fc3e-2ae6-48c1-95b6-ed82f9b8619e の値が ステータスIDになっています。アップサートステータスAPIのエンドポイントURLでこの ステータスIＤを渡すと、個人レコードの一括データアップサートのステータスを取得できます。

{
    "result": true,
    "requestId": "7581e498-c37e-4057-8fc9-c8d4d543de1a",
    "data": {
        "statusId": "e3f66752-bd71-4826-b9e0-892f7c0a841e"
    }
}

メソッド

ゲット

エンドポイントのURL

https://personapi.gainsightcloud.com/v1/peoplemgmt/v1.0/people/async/status/{statusId}

このエンドポイントURLでは:

• personapi.gainsightcloud.comがGainsightに接続できるドメインです。あくまで参考です。
• 非同期: 1回のAPIコールで複数の個人レコードを挿入または更新するためのメソッドを表します。
• statusId: 非同期アップサートAPIレコードリクエストがAPI を通じて送信されたときに生成されるジョブIDを表します。

statusIdを使用すると、エンドポイントURLは /v1/peoplemgmt/v1.0/people/async/status/a679fc3e-2ae6-48c1-95b6-ed82f9b8619eのようになります

リクエスト本文のサンプル

このステータスAPIは、対応するAPIコールのステータスをAPIレスポンスで応ずるものです。以下のいずれかのステータスを受けることができます：

• INIT （開始済み）
• INPROGRESS
• 完了

以下は、ステータスINITのAPIレスポンスの例です:

{
    "result": true,
    "requestId": "069360c6-03b3-4acf-8c7e-17ae0963ecd2",
    "data": {
        "status": "INIT"
    }
}

以下は、ステータスINPROGRESSのAPIレスポンスの例です:

{
    "result": true,
    "requestId": "069360c6-03b3-4acf-8c7e-17ae0963ecd2",
    "data": {
        "status": "INPROGRESS"
    }
}

レコードの挿入や更新が完了するまでには、最大で30分かかります。アップサートが完了するまで、ステータスはINITまたはINPROGRESSのいずれかで表示されます。API呼び出しのステータスが完了の場合、APIレスポンス本文は以下の情報を持ちます:

• 各レコードのステータスを成功または失敗のいずれかのアップサートステータス。
• 挿入または更新に成功した各レコードのPersonGsid 。
• errorCode、errorMessageなど、レコードのアップサートに失敗した際のエラーの詳細。

Gainsightのエラーコードの全リスト、エラーの説明、その理由については、「その他のリソース」セクションにある「個人API のエラーコード」の記事をご参照ください。

以下は、全レコードのアップサートに成功した完了と成功のステータスを持つAPIレスポンスの例です：

{
    "result": true,
    "requestId": "069360c6-03b3-4acf-8c7e-17ae0963ecd2",
    "data": {
        "response": [
            {
                "status": "SUCCESS",
                "personGsid": "1P04FB5W1VECWNJCCVSLYPA6V8DCGNQ58SZ8"
            },
            {
                "status": "SUCCESS",
                "personGsid": "1P04FB5W1VECWNJCCVUISQCMJQ7AR3H72NS8"
            },
            {
                "status": "SUCCESS",
                "personGsid": "1P04FB5W1VECWNJCCVH1M411WI4YP6E2JJSY"
            }
        ],
        "status": "COMPLETED"
    }
}

以下は、いくつかのレコードのアップサート時にステータスが完了および成功で、エラー詳細のあるいくつかのレコードのアップサート時に失敗となるAPIレスポンスの例です:

{
    "result": true,
    "requestId": "069360c6-03b3-4acf-8c7e-17ae0963ecd2",
    "data": {
        "response": [
            {
                "status": "SUCCESS",
                "personGsid": "1P04FB5W1VECWNJCCVSLYPA6V8DCGNQ58SZ8"
            },
            {
                "status": "SUCCESS",
                "personGsid": "1P04FB5W1VECWNJCCVUISQCMJQ7AR3H72NS8"
            },
            {
                "status": "FAILURE",
                "errors": [
                  {
                "field": "Company_ID",
                "invalidValue": [
                    {
                        "Name": "Simplify, Inc.",
                        "Company_ID":  "RLS_SOURCE_LOOKUP_FIELD_NOT_RESOLVED"
                    }
                ],
                "errorCode": "RLS_SOURCE_LOOKUP_FIELD_NOT_RESOLVED",
                "errorMessage": "ResolveLookupService source lookup field not resolved"
            }
]
            }
        ],
        "status": "COMPLETED"
    }
}

パラメーター

以下は、個人、会社個人、および関係個人オブジェクトのパラメーターです。

成功レスポンスのサンプル

{
  "result": true,
  "requestId": "8484e4fa-f520-4cdc-a4a4-acbec39a0648",
  "data": {
    "errors": [
      {
        "details": [
          {
            "errors": [
              {
                "message": "Internal server error",
                "code": "GSOBJ_PEOPLE1002"
              }
            ]
          }
        ]
      }
    ]
  },
  "message": "FAILED_WHILE_PROCESSING"
}

失敗レスポンスのサンプル

{
  "result": false,
  "requestId": "9d4a874f-dd0e-4806-b91f-e1cf5405e371",
  "data": {}
}

メソッド

ゲット

エンドポイントのURL

https://personapi.gainsightcloud.com/v1/peoplemgmt/v1.0/people/gsid

このエンドポイントURLでは、

• personapi.gainsightcloud.comがGainsightに接続できるドメインです。あくまで参考です。
• ピープルは、個人、会社個人、関係個人の各オブジェクトからレコードを取得することを表しています。
• gsid: 個人レコードの一意のGSIDを表します。これは、個人オブジェクトからレコードの詳細を取得し、会社個人オブジェクトと関係個人オブジェクトからそれぞれレコードの会社および関係関連の詳細を取得するのに役立ちます。

パラメーター

以下は、個人、会社個人、および関係個人オブジェクトのパラメーターです。

成功レスポンスのサンプル

APIリクエストが成功すると、レスポンスとしてHTTPステータスコード200が返されます。成功レスポンスのフォーマットは以下の通りです。エンドポイントURLで渡されたGSIDが既存レコードの個人gsidと一致する場合、システムは個人、会社個人、関係個人オブジェクトの各フィールドの値を取得します。フィールドに値が存在しない場合は、成功レスポンスでNULLとなります。成功レスポンスの例を以下に示します:

{
    "result": true,
    "requestId": "b31b204c-6df8-444a-bfc7-d922a98bbebe",
    "data": {
        "email": "jsmith@abc.com",
        "createddate": "2018-06-05T12:03:16.417",
        "firstname": "John",
        "timezone": null,
        "dynamicresolutionkey": null,
        "modifieddate": "2018-06-05T12:03:16.417",
        "name": "John Smith",
        "lastname": "smith",
        "externalrecordid__gc": null,
        "masterrecordid": null,
        "middlename": null,
        "masteravatartypecode": null,
        "location": "United States",
        "gsid": "1P04AB23JMJA97MWFYJM8PQO1KQTAYV5MXJ1",
        "companies": [
            {
                "modifieddate": "2018-06-05T12:04:10.81",
                "company_id": {
                    "Id": "1P04QNK6ENCURXXDZW9WWWWWWWWWWTZCAAAA",
                    "name": "abc, Inc."
                },
                "gsid": "1C01KDEEJ1EH9CQP5LE79JLEPK9AH63AKWS1",
                "active": true,
                "isprimarycompany": null,
                "role": "1I0054U9FAKXZ0H26H4PSEVL0V2MP7H680C4",
                "manager": null,
                "createddate": "2018-06-05T12:04:10.81",
                "person_id": {
                    "Id": "1P04AB23JMJA97MWFYJM8PQO1KQTAYV5MXJ1",
                    "name": "John Smith"
                },
                "title": "Executive Sponsor",
                "relationships": [
                    {
                        "person_id": {
                            "Id": "1P04AB23JMJA97MWFYJM8PQO1KQTAYV5MXJ1",
                            "name": "John Smith"
                        },
                        "relationship_type_id": null,
                        "manager": null,
                        "company_id": {
                            "Id": "1P04QNK6ENCURXXDZW9WWWWWWWWWWTZCAAAA",
                            "name": "abc, Inc."
                        },
                        "createddate": "2018-06-05T12:06:29.023",
                        "isprimarycompany": null,
                        "role": null,
                        "relationship_id": {
                            "Id": "1I00V4ALRX6A6ZOEQ0FNJ3CXSRAVFFWJBBB1",
                            "name": "Asia Pacific"
                        },
                        "gsid": "1C03IGJ69L7HWHM6EZQ1WP8952BL2V8GKCY8",
                        "title": "Executive Sponsor",
                        "company_person_id": {
                            "Id": "1C01KDEEJ1EH9CQP5LE79JLEPK9AH63AKWS1"
                        },
                        "active": true,
                        "modifieddate": "2018-06-05T12:06:29.023"
                    }
                ]
            }
        ]
    }
}

上記のサンプル成功レスポンスでは、

• データ フィールドは、個人オブジェクトのフィールド・値のペアを持ちます。
• 会社フィールドには、ルックアップフィールドである会社IDと個人IDと名前フィールドのそれぞれの値を含む会社個人オブジェクトのフィールド・値のペアがあります。
• 関係フィールドには、関係個人オブジェクトのフィールド・値のペアがあり、ルックアップ フィールドの 会社ID、関係ID、個人ID、および名前フィールドのそれぞれの値も含まれます。

失敗レスポンスのサンプル

{
  "result": false,
  "errorCode": "GS_APIG_2401",
  "errorDesc": "Unauthorized",
  "requestId": "b0e79bb9-7404-4e5b-8d51-30344f95a396",
  "message": "Unauthorized"
}

メソッド

ゲット

エンドポイントのURL

https://personapi.gainsightcloud.com/v1/peoplemgmt/v1.0/people?Email=jsmith@abc.com

上記のエンドポイントURLにおいて、

• personapi.gainsightcloud.comがGainsightに接続できるドメインです。あくまで参考です。
• ピープルは、個人、会社個人、関係個人の各オブジェクトからレコードを取得することを表しています。
• gsid: 個人レコードの一意のGSIDを表します。これは、個人オブジェクトからレコードの詳細を取得し、会社個人オブジェクトと関係個人オブジェクトからそれぞれレコードの会社および関係関連の詳細を取得するのに役立ちます。

パラメーター

以下は、個人、会社個人、および関係個人オブジェクトのパラメーターです。

成功レスポンスのサンプル

APIリクエストが成功すると、レスポンスとしてHTTPステータスコード200が返されます。成功レスポンスのフォーマットは以下の通りです。エンドポイントURLに記載されたメールは、個人オブジェクトのレコードを識別するための一意の識別子として使用され、個人、会社個人、および関係個人個人オブジェクトのこのレコードの各フィールドから値を取得します。フィールドに値が存在しない場合は、成功レスポンスでNULLとなります。成功レスポンスの例を以下に示します:

{
    "result": true,
    "requestId": "b31b204c-6df8-444a-bfc7-d922a98bbebe",
    "data": {
        "email": "jsmith@abc.com",
        "createddate": "2018-06-05T12:03:16.417",
        "firstname": "John",
        "timezone": null,
        "dynamicresolutionkey": null,
        "modifieddate": "2018-06-05T12:03:16.417",
        "name": "John Smith",
        "lastname": "smith",
        "externalrecordid__gc": null,
        "masterrecordid": null,
        "middlename": null,
        "masteravatartypecode": null,
        "location": "United States",
        "gsid": "1P04AB23JMJA97MWFYJM8PQO1KQTAYV5MXJ1",
        "companies": [
            {
                "modifieddate": "2018-06-05T12:04:10.81",
                "company_id": {
                    "Id": "1P04QNK6ENCURXXDZW9WWWWWWWWWWTZCAAAA",
                    "name": "abc, Inc."
                },
                "gsid": "1C01KDEEJ1EH9CQP5LE79JLEPK9AH63AKWS1",
                "active": true,
                "isprimarycompany": null,
                "role": "1I0054U9FAKXZ0H26H4PSEVL0V2MP7H680C4",
                "manager": null,
                "createddate": "2018-06-05T12:04:10.81",
                "person_id": {
                    "Id": "1P04AB23JMJA97MWFYJM8PQO1KQTAYV5MXJ1",
                    "name": "John Smith"
                },
                "title": "Executive Sponsor",
                "relationships": [
                    {
                        "person_id": {
                            "Id": "1P04AB23JMJA97MWFYJM8PQO1KQTAYV5MXJ1",
                            "name": "John Smith"
                        },
                        "relationship_type_id": null,
                        "manager": null,
                        "company_id": {
                            "Id": "1P04QNK6ENCURXXDZW9WWWWWWWWWWTZCAAAA",
                            "name": "abc, Inc."
                        },
                        "createddate": "2018-06-05T12:06:29.023",
                        "isprimarycompany": null,
                        "role": null,
                        "relationship_id": {
                            "Id": "1I00V4ALRX6A6ZOEQ0FNJ3CXSRAVFFWJBBB1",
                            "name": "Asia Pacific"
                        },
                        "gsid": "1C03IGJ69L7HWHM6EZQ1WP8952BL2V8GKCY8",
                        "title": "Executive Sponsor",
                        "company_person_id": {
                            "Id": "1C01KDEEJ1EH9CQP5LE79JLEPK9AH63AKWS1"
                        },
                        "active": true,
                        "modifieddate": "2018-06-05T12:06:29.023"
                    }
                ]
            }
        ]
    }
}

上記のサンプル成功レスポンスでは、

• データ フィールドは、個人オブジェクトのフィールド・値のペアを持ちます。
• 会社フィールドには、ルックアップフィールドである会社IDと個人IDと名前フィールドのそれぞれの値を含む会社個人オブジェクトのフィールド・値のペアがあります。
• 関係フィールドには、関係個人オブジェクトのフィールド・値のペアがあり、ルックアップ フィールドの 会社ID、関係ID、個人ID、および名前フィールドのそれぞれの値も含まれます。

失敗レスポンスのサンプル

{
   "result": true,
   "requestId": "ffce0c4e-ad8f-4704-8932-2f7e1149ba05",
   "data": {}
}

メソッド

削除

エンドポイントのURL

https://personapi.gainsightcloud.com/v1/peoplemgmt/v1.0/people

このエンドポイントURLでは、

• personapi.gainsightcloud.comがGainsightに接続できるドメインです。あくまで参考です。
• ピープルは、個人、会社個人、関係個人の各オブジェクトから特定のレコードを削除することを表しています。

リクエスト本文のサンプル

このAPIのリクエスト本文に個人レコードのGSIDを渡すことができます。個々の個人レコード、これに対応する会社個人、関係個人のレコード、および他のGainsightオブジェクトの個人参照のレコードが削除されます。

[
"1P04ARSY3839P6I6ECT3SZV21QW0RHARBU90",
"1P04ARSY3839P6I6ECN85PJ739P2QLZE2QKW",
"1P04ARSY3839P6I6ECKAX77N1RIABCUJ59GK"
]

注意:

• APIコールごとに最大5000個のGSIDを渡して、Gainsight個人オブジェクトからGSIDを削除することができます。
• 1時間あたり最大100回の削除 APIコールが可能です。

パラメーター

以下は、個人、会社個人、および関係個人オブジェクトのパラメーターです。

成功レスポンスのサンプル

削除 API のサンプルレスポンスは、削除RequestId、ステータス、カウントを返します。削除RequestId は、提出されたジョブのステータスIDを表し、GET 削除ステータス APIを使用して個人レコードの削除ステータスを取得するのに役立ちます 。以下の3つのステータスのいずれかを受けることができます：

• INIT - 初期化、リクエスト受付
• INPROGRESS - リクエストは進行中
• 完了 - リクエストは完了

カウントは、1つのジョブで処理されたレコードの数を表します。

{
    "result": true,
    "requestId": "b69ffec9-0893-400e-93ce-47824a888c52",
    "data": {
        "deleteRequestId": "b69ffec9-0893-400e-93ce-47824a888c52",
        "status": "INIT",
        "count": 0
    }
}

失敗レスポンスのサンプル

{
  "result": false,
  "requestId": "b0f78892-24ef-4580-89b2-66e36ae1ba6c"
}

メソッド

ゲット

エンドポイントのURL

https://personapi.gainsightcloud.com/v1/peoplemgmt/v1.0/people/delete/status/{deleteRequestId}

このエンドポイントURLでは、

• personapi.gainsightcloud.comがGainsightに接続できるドメインです。あくまで参考です。
• ピープルは、削除ステータスを確認するために、個人、会社個人、関係個人の各オブジェクトからレコードを特定することを表しています。
• 削除RequestId は、個人レコードの削除リクエストのステータスを取得するのに役立ちます。削除RequestIdに関する詳細情報については、削除APIセクションをご参照ください。

パラメーター

以下は、個人、会社個人、および関係個人オブジェクトのパラメーターです。

成功レスポンスのサンプル

GET 削除ステータス APIは、削除RequestId、ステータス、 カウントを返すサンプルレスポンスです。削除RequestIdは、エンドポイントURLで渡したIDです。ステータスは、削除 APIジョブのステータスを表します。以下の3つのステータスのいずれかを受けることができます：

• INIT - 初期化、リクエスト受付
• INPROGRESS - リクエストは進行中
• 完了 - リクエストは完了

カウントは、削除APIのジョブで処理されたレコードの数を表します。

{
    "result": true,
    "requestId": "1b49a9e7-935a-47b2-b5ff-5f9c5dcd14b7",
    "data": {
        "deleteRequestId": "b69ffec9-0893-400e-93ce-47824a888c52",
        "status": "COMPLETED",
        "count": 1
    }
}

失敗レスポンスのサンプル

{
  "result": false,
  "requestId": "b0f78892-24ef-4580-89b2-66e36ae1ba6c"
}

メソッド

入力

エンドポイントURL

https://demo-gsptest1.gainsightcloud...gestion/people

リクエスト本文の例

{
    "records": [
        {
            "Name": "John Smith",
            "FirstName": "John",
            "LastName": "Smith",
            "Email": "jsmith@gs.com",
            "companies": [
                {
                    "Company_ID": "1P022A6Z2DWEK48YJM70JL88EWWA8Y0MET52",
                    "IsPrimaryCompany": "true",
                    "relationships": [
                        {
                            "Role": "Admin",
                            "IsPrimaryCompany": "true",
                            "Relationship_ID": "1P0589D9GZXBR11L3198SKRYVPPDQ0YXPL9G"
                        },
                        {
                            "Role": "Admin",
                            "IsPrimaryCompany": "true",
                            "Relationship_ID": "1P0589D9GZXBR11L3198SKRYVPPDQ0YXPL9G"
                        }
                    ]
                }
            ]
        },
        {
            "Name": "Steven Ferguson",
            "FirstName": "Steven",
            "LastName": "Ferguson",
            "Email": "sferguson@drivedata.com",
            "companies": [
                {
                    "Company_ID": "1P022A6Z2DWEK48YJM70JL88EWWA8Y0MET52",
                    "IsPrimaryCompany": "true",
                    "relationships": [
                        {
                            "Role": "Executive Sponsor",
                            "IsPrimaryCompany": "true",
                            "Relationship_ID": "1P0589D9GZXBR11L31AIRD85YY0HG8XT0O37"
                        }
                    ]
                }, {
                    "Company_ID": "1P022A6Z2DWEK48YJME2XUU84B6OTTHEXDH6",
                    "IsPrimaryCompany": "true",
                    "relationships": [
                        {
                            "Role": "Executive Sponsor",
                            "IsPrimaryCompany": "true",
                            "Relationship_ID": "1P0589D9GZXBR11L31AIRD85YY0HG8XT0O37"
                        }
                    ]
                }
            ]
        }
    ]
}'

パラメータ