Employer Data API

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

 

Overview

The Employer Data API allows ATS partners to create and update employer entities on Indeed and the Indeed PLUS platform.

An employer on Indeed represents a company or organization that posts jobs. Every employer has a unique ID, name, and various attributes that help job seekers learn about potential workplaces.

Key concepts

• Employer entities: Created through the API have no relationship with Indeed employer accounts
• Prerequisites: You must create an employer before you create a job associated with that employer
• Moderation: Indeed reviews all employer data for completeness and appropriateness

Quick start

1. 1.
   Set up authentication
2. 2.
   Create your first employer
3. 3.
   Update employer information
4. 4.
   View Japan-specific requirements (Japan partners only)
5. 5.
   Troubleshooting

Reference information: supported locales and company sectors.

Authentication

All Employer Data API operations require 2-legged OAuth authentication:

1. Get a 2-legged OAuth token
2. Ensure your OAuth app has employer creation/update permissions (granted when you become an Indeed partner)

For more information, see GraphQL at Indeed.

Employer data

If you are an ATS partner, inform your employer clients about what data of theirs you send to Indeed, and how Indeed uses that data.

If someone with more authority than you provides Indeed with employer data, Indeed might overwrite your provided employer data.

Scopes of employer attributes

Indeed may display employer data differently based on the country and locale. Attributes that you pass to patchEmployer have different scopes so Indeed can choose the optimal combination of attributes to provide employer information to job seekers.

Employer data have these scopes:

1. Global scope: No matter in which country the employer operates, the value is the same.
   • The global attributes are employerName and employerType.
2. Country scope: The attribute value can differ by location.
   • countrySpecificAttributes contains all country-scope attributes.
   • When you update country-scope attributes, provide an ISO 3166-1 two-letter country code value in the country field in countrySpecificAttributes.
3. Locale scope: You can localize the attribute value by country and language.
   • localeSpecificAttributes contains all locale-scope attributes.
   • When you update locale-scope attributes, provide an ISO 3166-1 two-letter country code in the country field and an ISO 639-1 two-letter language code in the language field in localeSpecificAttributes. For the valid combinations of language and country, see Supported locales.
   • By default, the updated attributes are automatically set to global. localeSpecificAttributes contains the isGlobalDefault option, and its default value is true. The API returns this value for queries that specify a locale that does not have a translation. For example, if you query for a description in fr-CA to an employer without that translation, the API returns the global default.

Create an employer

To create an employer, use the patchEmployer GraphQL mutation. You must submit employer data before you create a job associated with the employer.

For authentication requirements, see Authentication.

Request

Call patchEmployer, passing in a PatchEmployerInput object, to submit employer data.

• id: A globally unique employer identifier. This object contains the following fields:
  • type: Uniquely identifies your ATS within the whole Indeed system. Indeed creates this during the onboarding process and provides it to you. Use the same value in every call to patchEmployer.
  • id: Uniquely identifies this employer within your ATS. This value is your employer identifier—some partners prefer to encrypt or hash it. Use the same value for all calls updating a given employer. To update a different employer, use that employer's unique identifier.
• employerName: Although this appears to be an optional field in PatchEmployerInput, this field is required when creating an employer. The value of employerName is copied to the global localizedName field, except when the request explicitly sets the global localizedName field.
• employerAttributes: An optional field for various employer data. If no employer attributes need to be set, you can ignore this field. You can update employer attributes after initially creating the employer. For the rules for updating each attribute, see Update an employer.

Indeed may display employer data differently based on the country and locale. For more information, see Scopes of employer attributes.

Example request

The following example creates a Japanese employer 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" 
            }
          }
        ]
      }
    }
  ) {
    responseCode
  }
}

Response

When the patchEmployer request succeeds, the API returns a PatchEmployerPayload object.

If the request fails, you receive an error response. To understand error responses, See Troubleshoot GraphQL errors.

Example response

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

Update an employer

To update employer attributes, call the patchEmployer mutation. Before you update employer data, create employer data.

For authentication requirements, see Authentication.

Request

To update employer attributes, call patchEmployer, passing in a PatchEmployerInput object. PatchEmployerInput contains the following fields:

• id: A globally unique employer identifier. This object contains the following fields:
  • type: Uniquely identifies your ATS within the whole Indeed system. Indeed creates this during the onboarding process and provides it to you. Use the same value in every call to patchEmployer.
  • id: Uniquely identifies this employer within your ATS. This value is your employer identifier—some partners prefer to encrypt or hash it. Use the same value for all calls updating a given employer. To update a different employer, use that employer's unique identifier.
• employerName: This field is optional, unless you want to update it. When this field is updated, the value of this field is copied to the global localizedName field, except when the request explicitly sets the global localizedName field.
• employerAttributes: An optional field for various employer data.

Indeed may display employer data differently based on the country and locale. For more information, see Scopes of employer attributes.

Update behavior

Each field supports these behaviors:

• Ignore: Omit a value for an attribute and it does not change.
• Update: Provide the value for the attribute in the query. If it differs from the stored value, the update succeeds.
• Delete: To delete an attribute, set its value to null. You cannot delete employerName.

Response

The response when you update an employer is the same as the response when you create an employer.

Examples

The following examples show how to update different employer data.

Update description

This code snippet 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

This code snippet 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 also update multiple employer attributes in a single request. One update request corresponds to one unique employer. If you have multiple employers, create multiple requests.

Don’t update multiple countries and locales in a single request. If you update them in one 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
        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
  }
}

Requirements for Japan partners

When creating or updating an employer using the patchEmployer mutation, all partners must include fields that are required by the schema.

In addition to the schema-required fields, Japanese partners must send certain fields when creating an employer to comply with Indeed PLUS policies and the law. However, these fields are not required when updating an employer if the field values aren't changing.

To ensure that you create and update employers successfully, follow this guide.

Required fields

This table lists required fields in PatchEmployerInput for the patchEmployer mutation when creating or updating an employer.

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	The value of employerName is copied to the global localizedName field, unless the request explicitly sets the global localizedName.
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 from EmployerType. For entities identified as JURIDICAL_PERSON, set a taxId in countrySpecificAttributes. Correctly identifies the company.
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		danger Setting isGlobalDefault: true and localizedName: null simultaneously deletes the default name, which is likely unintended.

Employer posting examples

The following examples show how to post employers with patchEmployer.

Example 1: Post a new employer

You can post initial employer data with the required fields and any optional fields that 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"
      }]
    }
  }) {
    responseCode
  }
}

Example 2: Add or update employer information

After posting employer data like in Example 1, you can add new fields and update existing fields later. For details about update behavior, see Update behavior.

The following example uses the same id.type and id.id fields as Example 1, so it updates the same employer. The example updates countrySpecificAttributes.phoneNumber to a new value, and adds localeSpecificAttributes.description as a new field.

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

Visible fields for Japan partners

The following employer fields are visible to job seekers on Indeed PLUS job boards in Japan. These fields belong to PatchEmployerInput, which is passed to the patchEmployer mutation.

Job boards' UX can and will change, so this list may not be up to date. Additionally, not every field appears in plain sight—some are behind buttons or even change the UX.

The fields are:

• employerName
• employerAttributes
  • countrySpecificAttributes
    • websiteUrl
    • phoneNumber
    • sectorSUIDs (the label corresponding to the SUID value)
  • localeSpecificAttributes
    • localizedName
    • phoneticName
    • description
    • headquarterAddress
  • leader
    • name

Troubleshoot errors

Common issues

• Authentication errors: Verify your OAuth token and permissions
• Validation errors: Check required fields for your target country
• Rate limiting: Implement exponential backoff for retries

For detailed troubleshooting:

• OAuth errors
• GraphQL errors

 

Was this page helpful?