Send Candidates APIガイド

候補者の応募をIndeedと同期します。

 

法的注意

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

Send Candidates APIワークフロー

1. 1.
   Send Candidates APIの概要：Send Candidates APIが候補者の応募をIndeedとどのように同期するかを学びます。
2. 2.
   認証。
3. 3.
   雇用主の登録：雇用主を登録し、登録情報を返します。
4. 4.
   応募の初期化と添付ファイルのアップロード：Indeedに対して応募バージョンをステージングし、添付ファイルのアップロードURLを生成して、そのURLにファイルをアップロードします。
5. 5.
   応募の送信：応募バージョンをIndeedに送信します。バージョンは送信順に非同期で公開されます。
6. 6.
   応募ステータスの追跡：応募ステータスと処理エラーを追跡します。
7. 7.
   応募の削除：応募とそのすべてのバージョンをIndeedから完全に削除します。
8. 8.
   GraphQLエラーのトラブルシューティング：GraphQLエラーを解決します。

Send Candidates APIリファレンス

• registerEmployer：雇用主を登録し、登録情報を返します。
• application.initialize：Indeedに対して応募バージョンをステージングし、添付ファイルのアップロード用URLを生成します。
• application.submit：応募を送信します。
• findStatuses：応募ステータスと処理エラーを追跡します。
• application.delete：応募を削除します。

Send Candidates APIの概要

Send Candidates APIは、候補者の応募の送信と追跡を行うための一連のワークフローを提供します。応募の送信には、初期化、添付ファイルのアップロード、送信の3つの手順が必要です。

初期化では、Indeedに対して応募バージョンをステージングし、添付ファイルのアップロード用URLを生成します。初期化のたびに、一意のapplicationVersionIdを持つバージョンが作成されます。初期化後、添付ファイルをアップロードして送信するまでに5分の猶予があります。

このAPIは、データを階層構造で整理します。applicationIdentifierオブジェクトには、応募を一意に識別する次のフィールドが含まれます。

応募の識別情報

フィールド	必須	説明
indeedRegistrationId	✅	Indeedの雇用主とパートナー側の雇用主を紐づける一意のID。登録時に提供されます。
atsCandidateId	⬜	1件以上のATS応募に関連付けられた候補者プロフィールのID。
atsApplicationId	✅	ATS内における応募の一意のID。
job.sourcedPostingId	✅	createSourcedJobPostingsが返す求人投稿ID。

この組み合わせが、1件の論理的な応募を定義します。同じapplicationIdentifierでinitializeを呼び出すたびに、その応募の新しいバージョンが作成されます。

注記

任意のフィールドを含め、すべてのフィールドがこの一意性に寄与します。たとえば、atsCandidateIdを含む応募は、他のフィールドがすべて同じであっても、このフィールドを含まない応募とは別の応募として扱われます。

添付ファイルをアップロードする際は、次の点にご注意ください。

• すべての添付ファイルはウイルスや有害なコンテンツがスキャンされます。安全でないファイルは削除されます。
• すべての添付ファイルの合計サイズは15MB（15,728,640バイト）を超えてはいけません。
• 1ファイルあたりのサイズは6MB（6,291,456バイト）を超えてはいけません。
• MD5ハッシュに基づき、重複する添付ファイルは許可されません。
• RESUMEとCOVER_LETTERの添付ファイルはそれぞれ最大1つです。追加のファイルにはOTHER_RESUMEまたはOTHER_COVER_LETTERを使用します。
• すべての添付ファイルには、Base64エンコードされた有効なMD5チェックサムが必要です。

人種、性別、年齢、障害の有無など、保護対象の属性情報に関する質問への回答はIndeedに公開されません。

応募を削除すると、その応募とすべてのバージョンがIndeedから完全に削除されます。削除した応募を再初期化することはできません。

注記

同じ応募に対する複数のミューテーション（initialize、submit、delete）を並行して実行しないでください。短時間に複数の操作を行うと、競合状態、想定外のデータ状態、公開バージョンの確認が困難になる、といった問題が生じる可能性があります。

認証

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で検索することもできます。

応募の初期化と添付ファイルのアップロード

Indeedに対して応募バージョンをステージングし、添付ファイルのアップロードURLを生成して、そのURLにファイルをアップロードします。

リクエスト – 応募の初期化

応募を初期化するには、initializeを呼び出します。この操作は、Indeedに対して応募バージョンをステージングし、添付ファイルのアップロード用URLを生成します。

認証

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

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

雇用主の登録

Indeedで雇用主を識別するため、indeedRegistrationIdに、registerEmployerがEmployerRegistrationで返すidを設定します。

雇用主はsendApplications機能が有効になっている必要があります。

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

initializeミューテーションのフィールド

フィールド	必須	説明
applicationIdentifier タイプ：AtsSyncCandidateSyncApplicationIdentifierInput!	✅	Indeed上の応募の一意のID。
applicant タイプ：AtsSyncCandidateSyncApplicantDetailsInput!	✅	応募者の完全な詳細情報。
questionsAndAnswers タイプ：[AtsSyncCandidateSyncApplicationQuestionAndAnswerInput!]!	⬜	スクリーニング質問と応募者の回答。それぞれプレーンテキスト文字列で指定します。
disposition タイプ：AtsSyncCandidateSyncApplicationDispositionInput!	✅	現在の応募ディスポジションステータス。ステータスマッピングの例については、Indeed標準ディスポジションステータスをご覧ください。
applicationLink タイプ：WebUrl!	✅	ご利用のシステムにある応募への直接リンク。
candidateLink タイプ：WebUrl	⬜	ご利用のシステムにある候補者プロフィールへの直接リンク。

mutation InitializeApplication($input:
  InitializeAtsSyncCandidateSyncApplicationInput!) {
  atsSyncCandidateSync {
    application {
      initialize(input: $input) {
        applicationVersionId
        attachments {
          fileType
          fileName
          contentType
          contentLength
          fileChecksum {
            checksum
          }
          url
        }
      }
    }
  }
}

レスポンス – 応募の初期化

応募初期化レスポンスのフィールド

フィールド	説明
applicationVersionId タイプ：ID!	新しい応募バージョン。送信時に使用します。
attachments タイプ：[AtsSyncCandidateSyncApplicationAttachment!]!	各添付ファイルのファイルデータをアップロードします。

initializeレスポンスで返される各添付ファイルについて、PUTリクエストでファイルデータをurlにアップロードします。initializeミューテーションのapplicant.attachmentsの値に一致する、次のヘッダーを含めます。

添付ファイルのアップロード

ヘッダー	値のソース	説明
Content-Type	contentType	添付ファイルの元のメディアタイプ。
Content-Length	contentLength	ファイルサイズ（バイト単位）。
Content-MD5	fileChecksum.checksum	MD5ハッシュ。 重要 checksumをBase64エンコードした値をContent-MD5ヘッダーの値として指定します。

応募の送信

認証

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

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

応募バージョンをIndeedに送信します。バージョンは送信順に非同期で公開されます。

雇用主の登録

Indeedで雇用主を識別するため、indeedRegistrationIdを指定します。雇用主はsendApplications機能が有効になっている必要があります。

これらのIDの管理方法については、Employer Registration APIをご覧ください。

リクエスト – 応募の送信

応募を送信するには、application.submitミューテーションを呼び出します。

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

submitミューテーションのフィールド

フィールド	必須	説明
indeedRegistrationId タイプ：ID!	✅	Indeedの雇用主アカウントへのリンク。
applicationVersionId タイプ：ID!	✅	application.initializeが返すバージョンID。

mutation SubmitApplication($input: SubmitAtsSyncCandidateSyncApplicationInput!) {
  atsSyncCandidateSync {
    application {
      submit(input: $input) {
        applicationVersionId
      }
    }
  }
}

レスポンス – 応募の送信

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

フィールド	説明
applicationVersionId タイプ：ID!	入力値と同じ値。必要に応じて監査用にログ記録します。

注記

初期化から5分以内に呼び出してください。送信前にすべての添付ファイルをアップロードしてください。添付ファイルが欠落していても応募は処理されますが、findStatusesはFILE_NOT_UPLOADEDエラーを返します。添付ファイルの処理が失敗した場合でも、応募は送信できます。処理は非同期ですが、送信順は維持されます。

応募ステータスの追跡

認証

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

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

送信後、応募バージョンのステータスをクエリして、処理状況の確認やエラーの特定を行います。

リクエスト – 応募ステータスの検索

ページングを使って応募バージョンのステータスをクエリするには、findStatusesを呼び出します。

このクエリを使用して、送信後の公開の進捗状況を追跡したり、バージョン履歴とともに一括ステータスを確認したりします。

findStatusesのフィルター

フィールド	フィルター対象
indeedRegistrationIds タイプ：ID!	雇用主。
applications タイプ：[AtsSyncCandidateSyncApplicationIdentifierInput!]!	応募ID。
applicationVersionIds タイプ：[ID!]!	応募バージョン。
applicationVersionStatusTypes タイプ：[AtsSyncCandidateSyncApplicationVersionStatusTypeInput!]!	ステータス。

query FindApplicationStatuses($input:
  AtsSyncCandidateSyncApplicationFindStatusesInput!$first: Int $after:
  String $last: Int $before: String) {
  atsSyncCandidateSync {
    application {
      findStatuses(input: $input first: $first after: $after last:
        $last before: $before) {
        applicationVersionStatuses {
          applicationVersionId
          applicationIdentifier {
            indeedRegistrationId
            atsCandidateId
            atsApplicationId
            job {
              sourcedPostingId
            }
          }
          status
          processingStatus
          errors
        }
        pageInfo {
          hasNextPage
          hasPreviousPage
          startCursor
          endCursor
        }
      }
    }
  }
}

応募の削除

認証

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

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

応募とそのすべてのバージョンをIndeedから完全に削除します。

雇用主の登録

Indeedで雇用主を識別するため、indeedRegistrationIdを指定します。雇用主はsendApplications機能が有効になっている必要があります。

これらのIDの管理方法については、Employer Registration APIをご覧ください。

リクエスト – 応募の削除

応募を削除するには、application.deleteミューテーションを呼び出します。

注記

この操作は元に戻せません。応募バージョンはすべてIndeedから削除され、再作成できません。削除後に新しいバージョンを作成することはできません。

deleteミューテーションのフィールド

フィールド	必須	説明
applicationIdentifier タイプ：AtsSyncCandidateSyncApplicationIdentifierInput!	✅	応募の一意のID。
deletedAt タイプ：DateTime!	✅	応募が削除されたタイムスタンプ。

mutation DeleteApplication($input: DeleteAtsSyncCandidateSyncApplicationInput!) {
  atsSyncCandidateSync {
    application {
      delete(input: $input) {
        applicationVersionId
      }
    }
  }
}

レスポンス – 応募の削除

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

フィールド	説明
applicationVersionId タイプ：ID!	この削除の一意のID。削除された応募の最終バージョンを参照します。

 

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