採用企業データAPI

Indeed および Indeed PLUSプラットフォームで採用企業エンティティを作成および更新します。直接採用企業はご利用いただけません。

 

概要

採用企業データAPIを使用すると、ATSパートナーは Indeed および Indeed PLUSプラットフォームで採用企業エンティティを作成および更新できます。

Indeed における採用企業は、求人を掲載する企業または組織を表します。すべての採用企業には一意の ID、名前、そして求職者が就業先候補について理解するのに役立つさまざまな属性があります。

主な概念

• 採用企業エンティティ — API を通じて作成した採用企業エンティティは、Indeed の採用企業アカウントとは関係ありません。
• 前提条件 — その採用企業に関連付けられた求人を作成する前に、採用企業を作成する必要があります。
• 審査 — Indeed は、すべての採用企業データについて完全性と適切性を審査します。

クイックスタート

1. 1.
   認証を設定する
2. 2.
   最初の採用企業を作成する
3. 3.
   採用企業情報を更新する
4. 4.
   日本固有の要件を確認する（日本のパートナーのみ）
5. 5.
   エラーをトラブルシュートする

参考情報: 対応ロケール および 企業セクター をご覧ください。

認証

採用企業データAPIのすべての操作には、2-legged OAuth 認証が必要です。

1. 2-legged OAuth トークンを取得する
2. OAuth アプリに採用企業の作成権限と更新権限があることを確認します。これらの権限は、Indeed パートナーになるときに付与されます。

詳細は、GraphQL at Indeed をご覧ください。

採用企業データ

ATSパートナーの場合は、Indeed に送信する採用企業データの内容と、Indeed がそのデータをどのように使用するかを、採用企業である顧客にお伝えください。

自社より高い権限を持つ第三者が Indeed に採用企業データを提供した場合、Indeed は自社が提供した採用企業データを上書きする場合があります。

採用企業属性のスコープ

Indeed は、国とロケールに応じて採用企業データを異なる方法で表示する場合があります。patchEmployer に渡す属性には異なるスコープがあり、Indeed は求職者に採用企業情報を表示するために最適な組み合わせを選択できます。

採用企業データには次のスコープがあります。

1. グローバルスコープ — 採用企業がどの国で事業を行っていても、値は同じです。
   • グローバル属性は employerName と employerType です。
2. 国スコープ — 属性値は所在地によって異なる場合があります。
   • countrySpecificAttributes には、国スコープの属性がすべて含まれます。
   • 国スコープの属性を更新する場合は、countrySpecificAttributes 内の country フィールドに ISO 3166-1 の 2 文字の国コード を指定します。
3. ロケールスコープ — 属性値を国と言語ごとにローカライズできます。
   • localeSpecificAttributes には、ロケールスコープの属性がすべて含まれます。
   • ロケールスコープの属性を更新する場合は、localeSpecificAttributes 内の country フィールドに ISO 3166-1 の 2 文字の国コード、language フィールドに ISO 639-1 の 2 文字の言語コード を指定します。有効な言語と国の組み合わせについては、対応ロケール をご覧ください。
   • デフォルトでは、更新した属性は自動的にグローバルに設定されます。localeSpecificAttributes には isGlobalDefault オプションがあり、そのデフォルト値は true です。API は、翻訳が存在しないロケールを指定したクエリに対してこの値を返します。たとえば、その翻訳がない採用企業に対して fr-CA の説明をクエリすると、API はグローバルデフォルトを返します。

採用企業を作成する

採用企業を作成するには、GraphQL patchEmployer ミューテーションを使用します。採用企業に関連付けられた求人を作成する前に、採用企業データを送信する必要があります。

認証要件については、認証 をご覧ください。

リクエスト

採用企業データを送信するには、PatchEmployerInput オブジェクトを渡して patchEmployer を呼び出します。

• id — グローバルに一意な採用企業識別子です。このオブジェクトには次のフィールドが含まれます。
  • type — Indeed システム全体で ATS を識別します。Indeed はセットアップ中にこの値を作成して提供します。すべての patchEmployer 呼び出しで同じ値を使用してください。
  • id — ATS 内でこの採用企業を一意に識別します。この値は自社の採用企業識別子です。一部のパートナーはこれを暗号化またはハッシュ化しています。特定の採用企業を更新するすべての呼び出しで同じ値を使用してください。別の採用企業を更新するには、その採用企業の一意の識別子を使用します。
• employerName — PatchEmployerInput では任意フィールドに見えますが、採用企業の作成時には必須です。リクエストで グローバル の localizedName フィールドを明示的に設定しない限り、employerName の値は グローバル の localizedName フィールドにコピーされます。
• employerAttributes — さまざまな採用企業データのための任意フィールドです。設定する必要がない場合は、このフィールドを省略できます。採用企業を最初に作成した後でも、採用企業属性は更新できます。各属性の更新ルールについては、採用企業を更新する をご覧ください。

Indeed は、国とロケールに応じて採用企業データを異なる方法で表示する場合があります。詳細については、採用企業属性のスコープ をご覧ください。

リクエストの例

次の例では、一般的なフィールドを使用して日本の採用企業を作成します。

mutation CreateEmployerExample {
  patchEmployer(
    input: {
      id: { 
        type: "YOUR_ATS_TYPE_FROM_INDEED"  
        id: "EMPLOYER_123"                 
      }
      employerName: "Example employer"
      employerAttributes: {
        employerType: JURIDICAL_PERSON
        countrySpecificAttributes: [
          { 
            country: "JP"
            websiteUrl: "https://example.com" 
            phoneNumber: "+81123456789"
          }
        ]
        localeSpecificAttributes: [
          {
            country: "JP"
            language: "ja"
            isGlobalDefault: true
            description: "Free text to describe the employer"
            localizedName: "ローカルネーム"
            headquarterAddress: "Minato-ku, Tokyo"
            leader: { 
              name: "Leader name" 
            }
          }
        ]
      }
    }
  ) {
    responseCode
  }
}

レスポンス

patchEmployer リクエストが成功すると、API は PatchEmployerPayload オブジェクトを返します。

リクエストが失敗した場合は、エラーレスポンスを受け取ります。エラーレスポンスの確認方法については、GraphQL エラーをトラブルシューティングする をご覧ください。

レスポンスの例

{
  "data": {
    "patchEmployer": {
      "responseCode": "OK"
    }
  }
}

採用企業を更新する

採用企業属性を更新するには、patchEmployer ミューテーションを呼び出します。採用企業データを更新する前に、まず採用企業データを作成してください。

認証要件については、認証 をご覧ください。

リクエスト

採用企業属性を更新するには、PatchEmployerInput オブジェクトを渡して patchEmployer を呼び出します。PatchEmployerInput には次のフィールドが含まれます。

• id — グローバルに一意な採用企業識別子です。このオブジェクトには次のフィールドが含まれます。
  • type — Indeed システム全体で ATS を識別します。Indeed はセットアップ中にこの値を作成して提供します。すべての patchEmployer 呼び出しで同じ値を使用してください。
  • id — ATS 内でこの採用企業を一意に識別します。この値は自社の採用企業識別子です。一部のパートナーはこれを暗号化またはハッシュ化しています。特定の採用企業を更新するすべての呼び出しで同じ値を使用してください。別の採用企業を更新するには、その採用企業の一意の識別子を使用します。
• employerName — このフィールドは更新する場合にのみ指定します。このフィールドを更新すると、リクエストで グローバル の localizedName フィールドを明示的に設定した場合を除き、その値は グローバル の localizedName フィールドにコピーされます。
• employerAttributes — さまざまな採用企業データのための任意フィールドです。

Indeed は、国とロケールに応じて採用企業データを異なる方法で表示する場合があります。採用企業属性のスコープ をご覧ください。

更新時の動作

各フィールドは次の動作をサポートします。

• 無視 — 属性の値を省略すると、変更されません。
• 更新 — クエリで属性の値を指定します。保存済みの値と異なる場合は更新されます。
• 削除 — 属性を削除するには、値を null に設定します。employerName は削除できません。

レスポンス

採用企業を更新したときのレスポンスは、採用企業を作成したときのレスポンス と同じです。

例

次の例は、さまざまな採用企業データを更新する方法を示しています。

説明を更新する

このコードスニペットは、ja-JP ロケールの採用企業の説明を更新します。

mutation UpdateDescription {
  patchEmployer(input: {
    id: {
      type: "TYPE_FROM_INDEED"
      id: "EMPLOYER_ID_IN_ATS"
    }
    employerAttributes: {
      localeSpecificAttributes: [{
        country: "JP"
        language: "ja"
        description: "Updated employer description"
      }]
    }
  }) {
    attributeUpdated
  }
}

説明を削除する

このコードスニペットは、値を null に設定して ja-JP ロケールの採用企業の説明を削除します。

mutation DeleteDescription {
  patchEmployer(input: {
    id: {
      type: "TYPE_FROM_INDEED"
      id: "EMPLOYER_ID_IN_ATS"
    }
    employerAttributes: {
      localeSpecificAttributes: [{
        country: "JP"
        language: "ja"
        description: null
      }]
    }
  }) {
    attributeUpdated
  }
}

複数の採用企業属性を更新する

1 回のリクエストで複数の採用企業属性を更新することもできます。1 つの更新リクエストは 1 つの一意な採用企業に対応します。複数の採用企業がある場合は、複数のリクエストを作成してください。

1 回のリクエストで複数の国やロケールを更新しないでください。1 つのリクエストでそれらを更新すると、結果が予測不能になる可能性があります。

mutation UpdateMultipleAttributes {
  patchEmployer(input: {
    id: {
      type: "TYPE_FROM_INDEED"
      id: "EMPLOYER_ID_IN_ATS"
    }
    employerName: "Example employer"
    employerAttributes: {
      employerType: JURIDICAL_PERSON
      countrySpecificAttributes: [{
        country: "JP"
        websiteUrl: "https://example.co.jp"
        phoneNumber: null
        taxId: "000000"
      }]
      localeSpecificAttributes: [{
        country: "JP"
        language: "ja"
        isGlobalDefault: true
        description: "Japanese employer description"
        localizedName: "Japanese local name"
        headquarterAddress: "Minato-ku, Tokyo"
        leader: {
          name: "Leader name"
        }
      }]
    }
  }) {
    attributeUpdated
  }
}

日本のパートナー向け要件

patchEmployer ミューテーションを使用して採用企業を作成または更新する場合、すべてのパートナーはスキーマで必須とされるフィールドを含める必要があります。

スキーマで必須のフィールドに加えて、日本のパートナーは Indeed PLUS のポリシーおよび法令に準拠するため、採用企業を作成するときに特定のフィールドを送信する必要があります。ただし、採用企業の更新時にフィールド値が変わらない場合は、これらのフィールドは必須ではありません。

採用企業を確実に作成および更新できるよう、このガイドに従ってください。

必須フィールド

次の表は、採用企業を作成または更新するときに patchEmployer ミューテーションの PatchEmployerInput で必須となるフィールドを示しています。

patchEmployer の必須フィールド

属性	必須	注記
type	✔ 採用企業の作成時と更新時	Indeed から提供された値を使用します。
id	✔ 採用企業の作成時と更新時	ATS 内でこの採用企業を一意に識別します。
employerName	✔ 採用企業の作成時	employerName の値は、リクエストで グローバル の localizedName を明示的に設定しない限り、グローバル localizedName フィールドにコピーされます。
countrySpecificAttributes.country	✔ 採用企業の作成時と更新時	JP に設定します。
countrySpecificAttributes.phoneNumber	✔ 採用企業の作成時
countrySpecificAttributes.sectorSUIDs	✔ 採用企業の作成時	企業セクター の該当する SUID 値を指定します。
employerAttributes.employerType	✔ 採用企業の作成時と更新時	EmployerType の適切な列挙値を指定します。 JURIDICAL_PERSON と識別されるエンティティの場合は、countrySpecificAttributes に taxId を設定します。 このフィールドは企業を正しく識別するために使用します。
localeSpecificAttributes.country	✔ 採用企業の作成時と更新時	JP に設定します。
localeSpecificAttributes.language	✔ 採用企業の作成時と更新時
localeSpecificAttributes.isGlobalDefault	✔ 採用企業の作成時と更新時
localeSpecificAttributes.headquarterAddress	✔ 採用企業の作成時
localeSpecificAttributes.localizedName		危険 isGlobalDefault: true と localizedName: null を同時に設定すると、デフォルト名が削除されます。これは意図しない動作である可能性が高いです。

採用企業の送信例

次の例は、patchEmployer を使用して採用企業を送信する方法を示しています。

例 1: 新しい採用企業を送信する

利用可能な任意フィールドと必須フィールドを使用して、初回の採用企業データを送信できます。

mutation CreateEmployerExample {
  patchEmployer(input: {
    id: {
      type: "YOUR_ATS_TYPE_FROM_INDEED"
      id: "EMPLOYER_123"
    }
    employerName: "株式会社テストその１"
    employerAttributes: {
      countrySpecificAttributes: [{
        country: "JP"
        phoneNumber: "+810312345678"
        sectorSUIDs: ["CS9YK"]
      }]
      localeSpecificAttributes: [{
        country: "JP"
        language: "ja"
        isGlobalDefault: true
        headquarterAddress: "東京都千代田区丸の内1-9-2"
      }]
    }
  }) {
    responseCode
  }
}

例 2: 採用企業情報を追加または更新する

例 1 のように採用企業データを送信した後で、新しいフィールドを追加したり、既存のフィールドを更新したりできます。更新時の動作について詳しくは、更新時の動作 をご覧ください。

次の例では、例 1 と同じ id.type フィールドと id.id フィールドを使用しているため、同じ採用企業が更新されます。この例では、countrySpecificAttributes.phoneNumber を新しい値に更新し、localeSpecificAttributes.description を新しいフィールドとして追加しています。

mutation PatchEmployerPhoneNumberAndDescription {
  patchEmployer(input: {
    id: {
      type: "YOUR_ATS_TYPE_FROM_INDEED"
      id: "EMPLOYER_123"
    }
    # Same id as in Example 1
    employerAttributes: {
      countrySpecificAttributes: [{
        country: "JP"
        #(phoneNumber) Modify an already - populated field
        phoneNumber: "+810323456789"
      }]
      localeSpecificAttributes: [{
        country: "JP"
        language: "ja"
        isGlobalDefault: true
        #(description) Add a new field
        description: "2004年に創業してから、世界中の人々の生活をサポートし続けてきました。人種・国籍問わず活躍できる職場を実現するための数々の施策に取り組んでおります。"
      }]
    }
  }) {
    attributeUpdated
    responseCode
  }
}

日本のパートナー向けの表示フィールド要件

次の採用企業フィールドは、日本の Indeed PLUS 求人ボードで求職者に表示されます。これらのフィールドは、patchEmployer ミューテーションに渡される PatchEmployerInput に属しています。

求人ボードの UX は変更される可能性があるため、この一覧は最新ではない場合があります。また、すべてのフィールドが見える場所に表示されるわけではなく、一部はボタンの背後に表示されたり、UX だけを変更したりする場合があります。

対象のフィールドは次のとおりです。

• employerName
• employerAttributes
  • countrySpecificAttributes
    • websiteUrl
    • phoneNumber
    • sectorSUIDs（SUID 値に対応するラベル）
  • localeSpecificAttributes
    • localizedName
    • phoneticName
    • description
    • headquarterAddress
  • leader
    • name

エラーをトラブルシュートする

よくある問題

• 認証エラー — OAuth トークンと権限を確認します。
• 検証エラー — 対象国で必須のフィールドを確認します。
• レート制限 — リトライに指数バックオフを実装します。

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

• OAuth エラー
• GraphQL エラー

 

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