APIエンドポイントを使用した一意のアンケートURLの作成

お知らせ：当社は、お客様により充実したサポート情報を迅速に提供するため、本ページのコンテンツは機械翻訳を用いて日本語に翻訳しています。正確かつ最新のサポート情報をご覧いただくには、本内容の英語版を参照してください。

概要

APIエンドポイント機能では、API呼び出しを通じて連絡先情報を受け取ることで、回答者ごとに一意のアンケートURLを生成します。これにより、外部システムから適切なタイミングでURL生成を自動的に実行でき、手動操作は不要です。生成されたURLは、独自のコミュニケーションチャネルを通じて配信できます。

たとえば、ある病院では、毎日数千件の予約を処理する患者管理システムを使用しています。予約が完了としてマークされると、病院のシステムがその患者の情報を使用してZoho Surveyの一意のアンケートURL生成APIエンドポイントを呼び出し、APIから一意のアンケートURLが返されます。病院は内部ツールを通じて、そのURLを患者に送信します。

利用例

Zoho Survey API連携を有効にできるシナリオは次のとおりです。

ECプラットフォームで購入商品の配送が完了した後、商品フィードバックアンケートを自動送信します。
旅行代理店はAPIを使用して、旅行から戻った顧客に旅行フィードバックアンケートを自動送信できます。
病院が予約後に患者へフィードバックアンケートを送信する場合。
イベント後アンケートを送信して、参加者からのフィードバックを収集し、イベントに関するインサイトを得ます。
学習プラットフォームで学生がコースを完了したときに、コースフィードバックアンケートを自動的にトリガーします。
新入社員が組織に入社したときに、オンボーディング体験アンケートを自動送信します。

用語。

OAuth- ユーザーのパスワードを共有することなく、保護されたリソースへの安全なアクセスを提供する業界標準のプロトコルです。

クライアント- エンドユーザーに代わってトリガー済み招待にアクセスするために、Zoho Surveyに要求を送信するアプリケーションです。

クライアントID- Zohoにアプリケーションを登録したときに受け取る一意の識別子です。

クライアントシークレット- Zohoにアプリケーションを登録したときに生成される一意のキーです。これは機密情報として管理する必要があります。

グラントトークン- アクセストークンとリフレッシュトークンの生成に使用する一時トークンです。組織固有のグラントトークンの生成は、1回限りの処理です。

アクセストークン- ユーザーのトリガー済み招待にアクセスするために、Zoho Survey APIに送信されるトークンです。アクセストークンにより、Zoho Survey APIへの安全かつ一時的なアクセスが可能になります。各アクセストークンは1時間のみ有効で、スコープで指定された操作にのみ使用できます。

リフレッシュトークン- 新しいアクセストークンの取得に使用できるトークンです。このトークンは、エンドユーザーによって取り消されるまで有効期限がありません。

APIレート制限-APIレート制限とは、任意の時点で同時に実行できるAPI呼び出しの最大数です。

前提条件。

有効なZoho Surveyユーザー認証情報。
Zoho Survey APIにアクセスするための有効な認証トークンまたはOAuth。
Zoho Surveyポータルに既存のメール配信があること。

手順。

APIトリガー招待を有効にするには、まずZoho Developer Consoleにクライアントを登録します。

アプリケーションの登録

クライアントIDとクライアントシークレットを生成するには、Zoho Developer Consoleにアプリケーションを登録します。

クライアントIDとクライアントシークレットが生成されたら、スコープ「ZohoSurvey.invitation.CREATE」を使用し、クライアントの種類に応じて組織固有のグラントトークンを生成します。グラントトークンは、セルフクライアントやサーバーベースのアプリケーションなど、特定のクライアントでのみ必要です。

生成されたグラントトークンをコピーします。各種アプリの種類に応じたクライアントIDとクライアントシークレットの生成方法については、詳細をご参照ください。

アクセストークンとリフレッシュトークンの生成

次に、ドメイン固有のZoho Accounts URLでグラントトークンを使用し、アクセストークンとリフレッシュトークンを生成します。

各ドメインと対応するAccounts URLは次のとおりです。

USの場合：https://accounts.zoho.com

AUの場合：https://accounts.zoho.com.au

EUの場合：https://accounts.zoho.eu

INの場合：https://accounts.zoho.in

CNの場合：https://accounts.zoho.com.cn

JPの場合：https://accounts.zoho.jp

CA（カナダ）の場合：https://accounts.zohocloud.ca

SA（サウジアラビア）の場合：https://accounts.zoho.sa

メモ：

サーバーベースのアプリケーションでは、アクセスタイプパラメーターの値をofflineにして認可要求を送信します。値がofflineの場合、初回の要求時にアクセストークンとともにリフレッシュトークンを受け取ります。アクセストークンの有効期限が切れた後は、リフレッシュトークンを使用してアクセストークンを再生成できます。

各アクセストークンは1時間のみ有効で、スコープで定義された操作にのみ使用できます。

新しいアクセストークンを生成するには、リフレッシュトークンを使用します。リフレッシュトークンに有効期限はなく、アクセストークンの有効期限が切れたときにアクセストークンを再生成するために使用できます。

APIトリガーURL

一意のURLコレクターを選択したら、［続ける］をクリックします。
API情報が以下のように画面に表示されます。
リクエストURLをコピーし、以下のように変数を設定します。

メソッド POST

Authorizationヘッダー：Zoho-oauthtoken e4af2b6xxxxxxxxxxxxxbaaba

（キー）（値）

Content-Type：application/json

リクエスト本文。

パラメーター	データ型	説明
emailAddress*	文字列	連絡先のメールアドレスを指定します
phoneNumber	文字列	連絡先の電話番号を指定します。
firstName	文字列	連絡先の名を指定します。
lastName	文字列	連絡先の姓を指定します。
variableOne	文字列	追加データを収集するために、この変数項目を追加できます
variableTwo	文字列	追加データを収集するために、この変数項目を追加できます
variableThree	文字列	追加データを収集するために、この変数項目を追加できます
variableFour	文字列	追加データを収集するために、この変数項目を追加できます
variableFive	文字列	追加データを収集するために、この変数項目を追加できます
variableSix	文字列	追加データを収集するために、この変数項目を追加できます

* 必須項目

メモ：

1件のPOST要求で複数の連絡先を追加できます。

サンプル要求

APIを実行するcurlコマンドを使用するには、以下のサンプル要求を参照してください。

curl 'https://survey.zoho.com/api/v1/external-private/portals/113436589/departments/soCNLR/surveys/123430000050422385/collectors/123430000050422419/distributions/123430000050460139/email/sendinvitation'

-H 'Authorization: Zoho-oauthtoken 1000.e4af2b6xxxxxxxxxxxxxbaaba.xa5xxxxxxxxxxxxxxxf'

-d '@contacts.json'

-X POST

この要求では、'@contacts.json'にサンプル入力データが含まれています。

サンプル入力

{

'contactsList': [

{

'emailAddress': 'bella@example.com',

'phoneNumber': '+1234567890',

'firstName': 'bella',

'lastName': 'steve',

'variableOne': 'variable1',

'variableTwo': 'variable2',

'variableThree': 'variable3',

'variableFour': 'variable4',

'variableFive': 'variable5',

'variableSix': 'variable6'

{

'emailAddress': 'john@example.com',

'phoneNumber': '+1234567890',

'firstName': 'John',

'lastName': 'steve'

}

]

}

HTTPSステータスコード

HTTPステータス	メッセージ	説明
200 OK		このステータスを受信した場合、APIトリガーが成功したことを示します。
530	ACCESS_RESTRICTED	配信がトリガー状態ではありません。APIリクエストURLを確認するか、トリガー型の媒体で新しい配信を作成してください。
530	NEED_RECIPIENTS	連絡先が空であるか、無効なメールアドレスが含まれています。
400	INVALID_REQUEST_METHOD	API URLにアクセスするためのHTTPメソッドが無効です。有効なリクエストメソッドを指定してください。
401	OAUTH_SCOPE_MISMATCH	クライアントに必要なスコープがありません。有効なスコープを持つ新しいクライアントを作成してください。
530	DISTRIBUTION_DISABLED	指定されたトリガーによる招待は無効になっています。
530	INVITATION_LIMIT_REACHED	トリガーの有効期限に対する招待数の上限に達しました。
530	DAILY_EINVITE_LIMIT_REACHED	1日の招待上限に達しました。
530	EINVITE_BOUNCE_RATE_EXCEEDED	アカウントのバウンス率の上限に達しました。
530	EINVITE_COMPLAINT_RATE_EXCEEDED	アカウントの苦情率の上限に達しました。

注意事項

リフレッシュトークンの取り消し：リフレッシュトークンを取り消すには、ドメイン固有のZoho Accounts URLを使用して、トークン取り消しリクエストを送信してください。詳細はこちら。

トークンの有効性：保存できるトークン数と、一度に送信できるリクエスト数には上限があります。詳細はこちら。

配信ごとの1分あたりの総リクエスト数に対するAPI上限は60です。