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. The API is available to ATS partners only. Employer Data API key concepts are:

• 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 is like to work there.
• Employer entities — Employers you create through the API have no relationship with 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. Get a 2-legged OAuth token.
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. Global scope — The value is the same in every country where the employer operates.
   • The global attributes are employerName and employerType.
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. 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.

• id — An object that uniquely identifies the employer across Indeed. It contains these fields:
  • type — Identifies your ATS across the Indeed system. Indeed creates this value during setup and provides it to you. Use the same value in every patchEmployer call.
  • id — Uniquely identifies this employer within your ATS. Some partners prefer to encrypt or hash it. Use the same value in every call that updates this employer.
• employerName — Required when you create an employer, even though PatchEmployerInput lists it as optional. Indeed copies this value to the global localizedName field unless the request sets that field explicitly.
• employerAttributes — Optional employer data. Omit this field if you have no attributes to set; you can add or update attributes after you create the employer. For the rules that govern 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

The following example creates an employer in Japan with common fields:

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

Response

patchEmployer returns a PatchEmployerPayload object. Its attributeUpdated field is true if employer attributes were updated. Errors appear in the standard GraphQL errors array. For more information 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 and its stored value does not change.
• Update — Provide a new value for the attribute in the request. If the value differs from the stored value, Indeed applies the update.
• Delete — Set the attribute to null. You cannot delete employerName.

Response

The response is the same as the create employer response.

Examples

The following examples show how to update different employer data.

Update description

The following example updates the employer description for the ja-JP locale:

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

The following 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 exactly one employer, so use a separate request for each employer.

Do not update multiple countries or locales in a single request, because 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
        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

All partners must include the fields that the schema requires when they create or update an employer with the patchEmployer mutation.

Japan partners must also send additional fields when they create an employer, to comply with Indeed PLUS policies and the law. These fields are not required when you update an employer, unless their values change.

Required fields

This table lists the fields that patchEmployer requires in PatchEmployerInput.

patchEmployer required 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.sectorSUIDs	✔ Create employer	Provide applicable SUID values from Company sector.
employerAttributes.employerType	✔ Create and update employer	Provide the appropriate enum value. For entities identified as JURIDICAL_PERSON, set a taxId in countrySpecificAttributes.
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

The following 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.

The following 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 can and does change, so this list might not be up to date. Some fields also appear only behind a button rather than in plain sight.

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?