Retrieve Candidates APIガイド

雇用主向けにIndeedから候補者情報を取得します。

 

法的注意

By using this API and its documentation and building an integration, you agree to the Additional API Terms and Guidelines.

雇用主向けにIndeedから候補者情報を取得するには、Retrieve Candidates APIを呼び出します。

Retrieve Candidates APIのワークフロー

Retrieve Candidates APIと連携した後、次の操作を呼び出せます。

1. 1.
   認証する。
2. 2.
   雇用主を登録する：雇用主を登録し、登録に関する情報を返します。
3. 3.
   未確認のアセットを取得する：未確認のアセットを、ステージングされた順（古いものから新しいもの）に取得します。
4. 4.
   時間範囲でアセットを取得する：確認済みのアセットを時間範囲で取得します。
5. 5.
   テストアセットを作成する：連携テスト用のテストアセットを作成します。
6. 6.
   GraphQLエラーをトラブルシューティングする：GraphQLエラーを解決します。

Retrieve Candidates APIリファレンス

• registerEmployer：雇用主を登録し、登録に関する情報を返します。
• fetchAssets：未確認のアセットを、ステージングされた順（古いものから新しいもの）に取得します。
• assetsByTimeRange：確認済みのアセットを時間範囲で取得します。
• stageAssets：連携テスト用のテストアセットを作成します。

認証する

Indeedパートナーになると、Indeedが連携用のアプリを作成します。Partner Consoleにログインして、アプリとOAuth認証情報（クライアントID、クライアントシークレット、および3-legged OAuthの場合は認可コード）を確認します。認証情報をアクセストークンと交換し、API呼び出しを認証します。

Candidate Sync APIの各操作には、OAuthトークンが必要です。

Candidate Sync API操作のOAuthトークンタイプ

API／操作	OAuthトークンタイプ
Employer Registration API 雇用主を登録する	認証 employer.ats_candidate.syncスコープを持つ、雇用主を表す3-legged OAuthトークンで認証します。このトークンは、雇用主のIndeedアカウントとそのATSアカウントを関連付けます。Indeedの管理者またはオーナーが作成する必要があります。 registerEmployerがスコープ不足のエラーを返す場合、トークンが雇用主に関連付けられていない可能性があります。 雇用主を表す3-legged OAuthトークンをご覧ください。
Employer Registration API 登録を更新する 登録を一覧表示する 雇用主の登録を解除する Send Candidates API 応募を初期化して添付ファイルをアップロードする 応募を送信する 応募ステータスを追跡する 応募を削除する Retrieve Candidates API 未確認のアセットを取得する 期間でアセットを取得する テストアセットを作成する	認証 2-legged OAuthトークンで認証します。アプリケーションは、ユーザー操作なしでIndeedの認可サーバーと直接認証します。 2-legged OAuthトークンをご覧ください。

アクセストークンはATSに安全に保管し、ユーザー間で共有しないでください。Indeedは、お客様のシステムが求人の信頼できる情報源（source of truth）であると想定しています。あるユーザーが投稿した求人に対して別のユーザーのアクセストークンを使用すると、Indeed上で他のユーザーの求人へのアクセス権がそのユーザーに付与される可能性があります。

アクセストークンを取得したら、クエリまたはミューテーションにこのトークンを含めます。最新の求人ステータスを確認するたびにユーザーにログインを求めずに済むよう、アクセストークンは有効期限が切れる前に更新することを推奨します。

Indeedと連携してAPIを呼び出すおよびスコープをご覧ください。

雇用主を登録する

Employer Registration APIを使用して雇用主を登録します。

リクエスト – 雇用主を登録する

雇用主を登録して登録情報を返すには、registerEmployerを呼び出します。

認証

employer.ats_candidate.syncスコープを持つ、雇用主を表す3-legged OAuthトークンで認証します。このトークンは、雇用主のIndeedアカウントとそのATSアカウントを関連付けます。Indeedの管理者またはオーナーが作成する必要があります。

registerEmployerがスコープ不足のエラーを返す場合、トークンが雇用主に関連付けられていない可能性があります。

雇用主を表す3-legged OAuthトークンをご覧ください。

次の入力フィールドを指定します。

registerEmployerの入力フィールド

フィールド	必須	説明
partnerEmployerId 型：ID!	✅	パートナーが提供する、雇用主を一意に識別するID。 1つのpartnerEmployerIdを複数のIndeedアカウントに登録できますが、各IndeedアカウントはATSごとに1つのpartnerEmployerIdのみをサポートします。同じIndeedアカウントで別のpartnerEmployerIdを使用すると、登録が指定したatsNameとpartnerEmployerIdに更新されます。
atsName 型：String!	✅	パートナーが提供する、雇用主が使用する名称。Indeedの雇用主にはこの名称が表示されます。

レスポンス – 雇用主を登録する

レスポンスはEmployerRegistrationを返します。以降のCandidate Sync APIの呼び出しで使用するため、登録のidを保存してください。後からpartnerEmployerIdを使ってfindRegisteredEmployersで検索することもできます。

未確認のアセットを取得する

未確認のアセットをステージングされた順（古いものから新しいもの）に取得するには、fetchAssetsを呼び出します。

認証

2-legged OAuthトークンで認証します。アプリケーションは、ユーザー操作なしでIndeedの認可サーバーと直接認証します。

2-legged OAuthトークンをご覧ください。

Retrieve Candidates APIは現在、Smart Sourcing経由の興味のある候補者に対応しています。今後のアップデートで新しいアセットタイプが追加される可能性があるため、レスポンス内の想定外のアセットタイプを適切に処理してください。すべてのアセットがAtsSyncCandidateSyncInterestedCandidateAssetとは限りません。

返されたemployerIdentifierは、登録作成時にIndeedに送信したIDと一致します。これを使用して、候補者を受け取る雇用主を識別します。

リクエスト – 未確認のアセットを取得する

このミューテーションは未確認のアセットを取得します。

未確認のアセットを取得します。

mutation FetchAssets($input: FetchAssetsAtsSyncCandidateSyncInput) {
  atsSyncCandidateSync {
    fetchAssets(input: $input) {
      token
      assets {
        id
        metadata {
          stagedAt
          stagedTest
          employerIdentifier
          completeSourceAttribution {
            enumKey
            name
          }
        }
        ...on AtsSyncCandidateSyncInterestedCandidateAsset {
          contact {
            candidate {
              email
              location
              name
              phone
              resume {
                pdf {
                  name
                  url
                }
              }
            }
            job {
              sourcedPostingId
            }
            tracking {
              recruiterEmail
            }
          }
        }
      }
    }
  }
}

次の入力フィールドを指定します。

fetchAssetsの入力フィールド

フィールド	タイプ	説明
limit	Int!	返すアセットの最大数。
token	String	前回のfetchAssets呼び出しで取得したトークン。このトークンを渡すと、そのバッチが確認済みとしてマークされ、再取得されなくなります。

レスポンス – 未確認のアセットを取得する

APIはFetchAssetsAtsSyncCandidateSyncPayloadレスポンスオブジェクトを返します。次のフィールドが含まれます。

fetchAssetsのレスポンスフィールド

フィールド	タイプ	説明
assets	[AtsSyncCandidateSyncAsset]!	次に取得可能なAtsSyncCandidateSyncAssetオブジェクト。
token	String	このバッチの確認トークン。次回のfetchAssets呼び出しに含めると、受信を確認して次のバッチをリクエストします。nullまたは空の場合はすべてのアセットが配信済みです。再度呼び出す前に標準のポーリング間隔だけ待ってください。

時間範囲でアセットを取得する

アセットを確認した後にIndeedから再取得するには、assetsByTimeRangeを呼び出します。このクエリはデータ損失からの復旧に使用します。アセットデータは自社のデータストアに永続化してください。ページネーションのベストプラクティスについては、GraphQL Cursor Connections Specificationをご覧ください。

認証

2-legged OAuthトークンで認証します。アプリケーションは、ユーザー操作なしでIndeedの認可サーバーと直接認証します。

2-legged OAuthトークンをご覧ください。

注記

新しいアセットを取得するには、fetchAssetsを使用します。

リクエスト – 時間範囲でアセットを取得する

開始日または終了日を省略した場合、クエリは最も古い確認日と最も新しい確認日をデフォルト値として使用します。

時間範囲で確認済みのアセットを取得します。

query AssetsByTimeRange($input: AtsSyncCandidateSyncAssetsByTimeRangeInput!,
  $after: String) {
  atsSyncCandidateSync {
    assetsByTimeRange(input: $input, after: $after) {
      assets {
        id
        metadata {
          employerIdentifier
          stagedAt
          stagedTest
          completeSourceAttribution {
            enumKey
            name
          }
        } 
        ... on AtsSyncCandidateSyncInterestedCandidateAsset {
          contact {
            candidate {
              email
              location
              name
              phone
              resume {
                pdf {
                  name
                  url
                }
              }
            }
            job {
              sourcedPostingId
            }
            tracking {
              recruiterEmail
            }
          }
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

レスポンス – 時間範囲でアセットを取得する

assetsByTimeRangeはfetchAssetsと同じアセットデータを返しますが、確認済みのアセットのみを返します。レスポンス – 未確認のアセットを取得するをご覧ください。

モックアセットは14日後に有効期限が切れ、assetsByTimeRangeのレスポンスに表示されなくなります。テストアセットを作成するをご覧ください。

テストアセットを作成する

サンドボックスモードでテスト候補者アセットを作成するには、stageAssetsを呼び出します。テストアセットは実際の候補者アセットと同じように動作します。fetchAssetsを使用してテストアセットを取得し、ワークフローをテストします。

認証

2-legged OAuthトークンで認証します。アプリケーションは、ユーザー操作なしでIndeedの認可サーバーと直接認証します。

2-legged OAuthトークンをご覧ください。

要件

テストアセットをステージングする前に、次を確認します。

• employerIdentifierは、registerEmployerで作成した雇用主登録のemployerIdentifierと一致している必要があります。
• sourcedPostingIdはUUIDである必要がありますが、既存の求人投稿に対応している必要はありません。
• モックアセットのデータはステージングから14日後に自動的に削除されます。

リクエスト – テストアセットを作成する

テストアセットを作成するには、次の手順を実行します。

1. 氏名、メールアドレス、電話番号、勤務地などのテスト候補者情報を指定して、stageAssetsを呼び出します。

   テスト履歴書を含めるには、includeResumeをtrueに設定します。

   APIは、ステージングされた各アセットに一意のIDを返します。

2. ステージングされた候補者を取得するには、fetchAssetsを呼び出します。

3. 連携が候補者データを処理することを確認します。

   モックアセットは、assetsのmetadataにあるstageTestフィールドで識別します。

連携テスト用のテスト候補者アセットを作成します。

mutation {
  atsSyncCandidateSync {
    stageAssets(input: {
      assets: [{
        smartSourcingContact: {
          metadata: {
            employerIdentifier: "employer-123"
          }
          contact: {
            candidate: {
              name: "Jane Smith"
              email: "jsmith@example.com"
              location: "Syracuse, New York 13209"
              phone: "+10001112223"
              includeResume: true
            }
            job: {
              sourcedPostingId: "e29aaba8-2cef-447f-a1e0-bcb7ec3fa730"
            }
            tracking: {
              recruiterEmail: "recruiter@example.com"
            }
          }
        }
      }]
    }) {
      ids
    }
  }
}

エラーをトラブルシューティングする

GraphQLにアクセスする前に発生する可能性があるOAuthエラーのトラブルシューティングについては、OAuthエラーのトラブルシューティングをご覧ください。

GraphQLエラーのトラブルシューティングについては、GraphQLエラーのトラブルシューティングをご覧ください。

 

このページは役に立ちましたか？