Employer Data API

Create and update employer entities on Indeed and the Indeed PLUS platform. Not available for direct employers.

 

API overview

Use the Employer Data API to create and update employers on Indeed and the Indeed PLUS platform. Only ATS partners can use the API. Key concepts:

• Employer — A company or organization that posts jobs on Indeed. Every employer has a unique ID, a name, and attributes that tell job seekers what it's like to work there.
• Employer entities — Employers you create through the API aren't linked to Indeed employer accounts.
• Order of operations — Create an employer before you create a job for that employer.
• Moderation — Indeed reviews all employer data for completeness and appropriateness.

---

API steps

---

1. Authenticate

Every Employer Data API operation requires a 2-legged OAuth token:

1. 1.
   Get a 2-legged OAuth token.
2. 2.
   Confirm that your OAuth app can create and update employers. Indeed grants these permissions when you become an Indeed partner.

For more information, see GraphQL at Indeed.

Employer data

Tell your employer clients what data you send to Indeed and how Indeed uses it.

Indeed might overwrite the employer data you send if a more authoritative source sends different data.

Scopes of employer attributes

Indeed might display employer data differently by country and locale. The attributes you pass to patchEmployer have different scopes, so Indeed can choose the best combination to show job seekers.

Employer data has three scopes:

1. 1.

   Global scope — The value is the same in every country where the employer operates.

   • The global attributes are employerName and employerType.
2. 2.

   Country scope — The value can differ by country.

   • countrySpecificAttributes contains every country-scope attribute.
   • To update a country-scope attribute, set its country field to an ISO 3166-1 two-letter country code (opens in a new window).
3. 3.

   Locale scope — The value can differ by country and language.

   • localeSpecificAttributes contains every locale-scope attribute.
   • To update a locale-scope attribute, set its country field to an ISO 3166-1 two-letter country code (opens in a new window) and its language field to an ISO 639-1 two-letter language code (opens in a new window). For valid combinations, see Supported locales.
   • The isGlobalDefault option defaults to true, which makes the attributes you update the global default. Indeed returns that global default when a query asks for a locale that has no translation. For example, if you request a description in fr-CA and the employer has no fr-CA translation, Indeed returns the global default.

---

2. Create an employer

To create an employer, use the GraphQL patchEmployer mutation.

For authentication requirements, see Authenticate.

Request

Call patchEmployer with a PatchEmployerInput object that contains these fields:

• id — Uniquely identifies the employer across Indeed. Contains these fields:

  • type — Identifies your ATS at Indeed. Indeed gives you this value during setup. Use the same value in every patchEmployer call.
  • id — Identifies this employer in your ATS. Some partners encrypt or hash it. Use the same value in every call for this employer.

• employerName — Required to create an employer, even though PatchEmployerInput lists it as optional. Indeed copies it to the global localizedName field unless you set that field yourself.

• employerAttributes — Optional, except for Japan partners. See Requirements for Japan partners. If you have no attributes to set yet, omit this field and add them later. For the rules for each attribute, see Update an employer.

Indeed might display employer data differently by country and locale. For more information, see Scopes of employer attributes.

Example request

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"
        sectorSUIDs: ["SUID-of-some-indeed-sector"]
        taxId: "000000"
      }]
      localeSpecificAttributes: [{
        country: "JP"
        language: "ja"
        isGlobalDefault: true
        description: "Free text to describe the employer"
        localizedName: "ローカルネーム"
        headquarterAddress: "Minato-ku, Tokyo"
        leader: {
          name: "Leader name"
        }
      }]
    }
  }) {
    attributeUpdated
  }
}

Response

patchEmployer returns a PatchEmployerPayload object. Its attributeUpdated field is true if Indeed updated employer attributes. Errors appear in the standard GraphQL errors array. For more about error responses, see Troubleshoot GraphQL errors.

---

3. Update an employer

To update employer attributes, call the patchEmployer mutation. Create the employer before you update it.

For authentication requirements, see Authenticate.

Request

Pass a PatchEmployerInput object with these fields:

• id — An object that uniquely identifies the employer across Indeed. Use the same type and id values you used to create the employer. For field details, see Request.
• employerName — Optional. Include it only to change the employer's name. Indeed copies the new value to the global localizedName field unless the request sets that field explicitly.
• employerAttributes — Optional employer data.

Indeed might display employer data differently by country and locale. For more information, see Scopes of employer attributes.

Update behavior

Each attribute supports three behaviors:

• Ignore — Omit the attribute. Its stored value doesn't change.
• Update — Send a new value for the attribute. If it differs from the stored value, Indeed applies the update.
• Delete — Set the attribute to null. You can't delete employerName.

Response

The response is the same as the create employer response.

Examples

These examples show how to update different employer data.

Update description

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
  }
}

Delete description

This example deletes the employer description for the ja-JP locale by setting it to null:

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

Update multiple employer attributes

You can update multiple attributes for one employer in a single request. Each request updates only one employer, so send a separate request for each employer.

Don't update multiple countries or locales in a single request. The results can be unpredictable.

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
        sectorSUIDs: ["SUID-of-some-indeed-sector"]
        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
  }
}

---

4. Troubleshoot errors

Common issues

• Authentication errors — Verify your OAuth token and confirm that your app can create and update employers.
• Validation errors — Confirm that you provided every field your target country requires.
• Rate limiting — Retry with exponential backoff.

For more information, see:

• Troubleshoot OAuth errors
• Troubleshoot GraphQL errors

---

Requirements for Japan partners

When you create or update an employer with the patchEmployer mutation, include every field the schema requires.

Japan partners must also send more fields when they create an employer, to comply with Indeed PLUS policies and the law. You don't need to send these fields when you update an employer unless their values change.

Required fields

This table shows which PatchEmployerInput fields are required and which are optional:

patchEmployer required and optional fields

Attribute	Required	Notes
type	✔ Create and update employer	Use the value that Indeed provides you.
id	✔ Create and update employer	Uniquely identifies this employer within your ATS.
employerName	✔ Create employer	Indeed copies this value to the global localizedName field unless the request sets that field explicitly.
countrySpecificAttributes.country	✔ Create and update employer	Set to JP.
countrySpecificAttributes.phoneNumber	✔ Create employer
countrySpecificAttributes.taxId		Employer's tax identifier. Limit: 100 characters. Japan: If employerType is JURIDICAL_PERSON, set to the corporate number (法人番号) for correct identification. If employerType is NATURAL_PERSON, this field is optional.
countrySpecificAttributes.sectorSUIDs	✔ Create employer	Provide applicable SUID values from Company sector.
employerAttributes.employerType	✔ Create employer	Set to the employer's type. For JURIDICAL_PERSON, also set taxId in countrySpecificAttributes. On update, required only when employer attributes change.
localeSpecificAttributes.country	✔ Create and update employer	Set to JP.
localeSpecificAttributes.language	✔ Create and update employer
localeSpecificAttributes.isGlobalDefault	✔ Create and update employer
localeSpecificAttributes.headquarterAddress	✔ Create employer
localeSpecificAttributes.localizedName		Setting isGlobalDefault: true and localizedName: null in the same request deletes the default name.

Employer posting examples

These examples show how to post employers with patchEmployer.

Example 1: Post a new employer

Post the required fields plus any optional fields you have.

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"
      }]
    }
  }) {
    attributeUpdated
  }
}

Example 2: Add or update employer information

After you post employer data as in Example 1, you can add new fields and update existing ones. For details, see Update behavior.

This example reuses the id.type and id.id values from Example 1, so it updates the same employer. It changes countrySpecificAttributes.phoneNumber and adds 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
  }
}

Visible fields requirements for Japan partners

Job board UX changes over time, so this list might be out of date. Some fields appear only behind a button, not on the page itself.

Job seekers on Indeed PLUS job boards in Japan can see these PatchEmployerInput fields:

• employerName

• employerAttributes

  • countrySpecificAttributes

    • websiteUrl
    • phoneNumber
    • sectorSUIDs — the label that corresponds to the SUID value

  • localeSpecificAttributes

    • localizedName

    • phoneticName

    • description

    • headquarterAddress

    • leader

      • name

---

References

• Supported locales
• Company sectors

 

Was this page helpful?