Sponsored Jobs API get started

Get started with the Sponsored Jobs API.

 

legal notice

Unless you have a written agreement with Indeed regarding your use of Indeed's APIs, by using this API or its documentation, you agree to apply the Indeed API Terms and the Additional API Terms and Guidelines to your use of Indeed's APIs.

• 2026-01-08:

  • Sponsored Jobs API usage policy: as of 2026-02-01, per-call charges apply in these markets:

    • EU markets and Switzerland (AT, BE, CH, DE, DK, EE, ES, FI, FR, GR, IE, IT, LU, NL, PL, PT, RO, SE): 3 EUR, or the equivalent in the advertiser's billing currency.
    • Other markets (AR, AU, BR, CA, CL, CO, CR, GB, ID, IN, MX, MY, NZ, PA, PH, SG, TH): 3 USD, or the equivalent in the advertiser's billing currency.

    Fees apply only when your monthly Sponsored Jobs campaign spend is less than your monthly API call cost.

    The policy applies to all paying Sponsored Jobs API customers except users of Indeed's proprietary ATS plugin.

    Eligibility: You can use the Sponsored Jobs API only if you sponsored a job in the last three calendar months.

    Monthly call limit: The maximum is the greater of:

    • Your previous month's Sponsored Jobs campaign spend.
    • Your credit limit.

    Monitor your usage: Call /apiquotausage to retrieve your current month's API usage.

    For recommended API usage patterns, see Sponsored Jobs API best practices to reduce call volume.

• 2026-01-08:

  • Sponsored Jobs API usage policy (US): as of 2024-12-01, Sponsored Jobs API customers pay for API usage based on their sponsorship spend. The policy does not apply to users of Indeed's proprietary ATS plugin.

    For recommended API usage patterns, see Sponsored Jobs API best practices to reduce call volume.

• Effective 2024-06-30: the GET /v1/stats/datastatus endpoint is decommissioned and returns HTTP 404. Use GET /v1/stats instead.

• Effective 2024-06-26: the GET /v1/campaigns/:campaignId/stats/:date and GET /v1/campaigns/:campaignId/stats/entryDates endpoints are decommissioned and return HTTP 404.

  Use GET /v1/campaigns/{campaignId}/stats instead.

• Effective 2024-06-26: the perPage parameter for GET /v1/campaigns is capped at 500. Requests with a higher value are rejected as invalid.

• Sunset of Sponsored Jobs legacy API:

  • 2021-08-01: migrate to the latest Sponsored Jobs API gateway, which uses the Indeed OAuth v2 endpoint and runs on infrastructure with higher availability and lower latency.

  • 2022-01-01: the Sponsored Jobs legacy API was sunset.

  • 2022-03-31: the Sponsored Jobs XML integration was sunset.

Review prerequisites, how-to guides with examples, FAQs, and troubleshooting.

Sponsored Jobs API prerequisites

Configure OAuth

Before you use the Sponsored Jobs API, you need:

• An Indeed account
• Your API client ID and secret
• Jobs in your Indeed account that are available to sponsor
• The employers associated with your account

Sponsored Jobs API OAuth

OAuth	Description
2-legged OAuth	The examples in this guide use the client credentials flow (2-legged OAuth). Use this OAuth flow if you are a direct employer, agency, or programmatic. For agencies and programmatics acting on behalf of an employer, Indeed recommends that the employer adds your Indeed account as a secondary user to their Indeed account. This enables you to use the client credentials flow (2-legged OAuth). Register your 2-legged OAuth app to get your client ID and secret: * Japan only: Use the Manage app credentials page. * Outside Japan: Use the Partner Console. If you cannot access the console, contact your Indeed representative or marketplacesupport@indeed.com.
3-legged OAuth	ATS partners must use the Authorization code flow (3-legged OAuth). When you become an Indeed partner, Indeed sets up an app for your integration. Sign in to Partner Console to view your app and OAuth credentials (client ID, secret, and authorization code for 3-legged OAuth). Exchange credentials for an access token to authenticate API calls.

OAuth v2 token scopes

A scope value is required when generating the auth token for each API call.

• Requesting a write scope also grants the permissions of the corresponding read-only scope.

  For example, employer.advertising.campaign also grants the permissions that employer.advertising.campaign.read grants.

• You can associate multiple scopes with one access token. Space-delimit the scopes.

  For example employer_access employer.advertising.campaign employer.advertising.campaign_report.read.

In your OAuth authorization code request, pass the scopes that correspond to the API endpoints you are calling.

Then, the end user chooses whether to grant you none, some, or all scopes that you requested.

Use this table to determine which scope to request for each API endpoint.

API quota usage

For this endpoint, get an access token with the employer_access scope. See Get access token that represents employer.

API quota usage

Verb	API endpoint	OAuth scope
GET	/v1/apiquotausage	employer.advertising.account.read

Account management

Account management scopes

Verb	API endpoint	OAuth scope	Access token type
GET	/v1/account	For employer account: employer.advertising.account.read	With employer_access scope. See Get access token that represents employer.
		For master account: employer.advertising.subaccount.read	Without employer parameter
GET	/v1/advertisers	employer.advertising.subaccount.read	Without employer parameter
GET	/v1/subaccounts	employer.advertising.subaccount.read	Without employer parameter
POST	/v1/subaccounts	employer.advertising.subaccount	Without employer parameter
GET	/v1/account/budget	employer.advertising.account.read	With employer_access scope. See Get access token that represents employer.
PATCH	/v1/account/budget	employer.advertising.account	With employer_access scope. See Get access token that represents employer.

Campaign management

For these endpoints, the access token type with the employer_access scope. See Get access token that represents employer.

Campaign management scopes

Verb	API endpoint	OAuth scope
GET	/v1/campaigns	employer.advertising.campaign.read
POST	/v1/campaigns	employer.advertising.campaign
GET	/v1/campaigns/{campaignId}	employer.advertising.campaign.read
PATCH	/v1/campaigns/{campaignId}	employer.advertising.campaign
GET	/v1/campaigns/{campaignId}/budget	employer.advertising.campaign.read
PATCH	/v1/campaigns/{campaignId}/budget	employer.advertising.campaign
GET	/v1/campaigns/{campaignId}/jobCount	employer.advertising.campaign.read
GET	/v1/campaigns/{campaignId}/properties	employer.advertising.campaign.read

Reports

For these endpoints, the access token type with employer_access scope. See Get access token that represents employer.

Reports scopes

Verb	API endpoint	OAuth scope
GET	/v1/campaigns/{campaignId}/stats	employer.advertising.campaign_report.read
GET	/v1/campaigns/{campaignId}/stats/{date}	employer.advertising.campaign_report.read
GET	/v1/campaigns/{campaignId}/stats/entryDates	employer.advertising.campaign_report.read
GET	/v1/stats	employer.advertising.campaign_report.read
GET	/v1/stats/{reportId}	employer.advertising.campaign_report.read

Get OAuth access token

To call the oauth/v2/tokens endpoint and get an access token, request the token that matches the API you want to call.

Most Sponsored Jobs API endpoints require an access token that represents an employer. You must therefore request employer_access scope in addition to the scopes required by the endpoints you plan to call, and include the employer parameter to specify the employer whose data you'll be accessing. However, if you have a master account and are calling subaccount management endpoint, omit the employer parameter when requesting the access token. You call the subaccount management endpoint through either:

GET /v1/subaccounts
POST /v1/subaccounts

API details for tokens endpoint

tokens endpoint

API URL	https://apis.indeed.com/oauth/v2/tokens
Request type	POST
Content type	application/json
Auth	None

Request parameters for tokens endpoint

tokens request parameters

Key	Value
client_id	Client ID. Get it from: * Japan only: Manage app credentials. For more information, see Credentials. * Outside Japan: Partner Console. If you cannot access the console, contact your Indeed representative or marketplacesupport@indeed.com.
client_secret	Client secret. Get it from: * Japan only: Manage app credentials. For more information, see Credentials. * Outside Japan: Partner Console. If you cannot access the console, contact your Indeed representative or marketplacesupport@indeed.com.
grant_type	client_credentials
scope	Depends on the endpoints that you call. For example, employer_access employer.advertising.account.read.
employer	Your employer account ID.

Sample response for tokens endpoint

{
  "access_token": "<access_token>",
  "scope": "employer.advertising.account.read employer_access",
  "token_type": "Bearer",
  "expires_in": 3600
}

How-to guides for campaign management

Create single-use campaign

This example creates a single-use campaign that runs for two weeks and sponsors jobs in two locations with a $500 budget.

1. Use an access token with the required scopes for a single-use campaign.

   Create single-use campaign

   scope	employer_access employer.advertising.campaign

2. Get the job source ID for the jobs.

   To get the job source ID, get employer account information. An employer can have more than one job source ID, one for each website or domain. The jobSourceList.id response field contains the job source ID for each site.

3. Create the single-use campaign.

   API details for a single-use campaign:

   API details for single-use campaign

   API URL	https://apis.indeed.com/ads/v1/campaigns (Sponsored Jobs API reference)
   Request type	POST
   Content type	application/json
   Auth	OAuth 2.0 bearer token

   Sample request for a single-use campaign:

   {
     "name": "Test Campaign Single-use",
     "status": "PAUSED",
     "trackingToken": "MyTrackingToken",
     "jobsSourceId": "[Your jobsSourceId from Step 2]",
     "jobsToInclude": "QUERY",
     "jobsQuery": "city:Aberdeen OR city:Glasgow",
     "budgetOnetimeLimit": 500,
     "startDate": "2021-09-01",
     "fixedEndDate": "2021-09-15"
   }

   Sample response for single-use campaign:

   {
     "meta": {
       "status": 201,
       "errors": null,
       "rootLocation": "https://apis.indeed.com/ads",
       "perPage": null,
       "links": [{
         "rel": "Campaign Info",
         "href": "/v1/campaigns/c8bxxxxxxxxx449"
       }]
     },
     "data": {
       "campaignId": "c8bxxxxxxxxx449"
     }
   }

4. View single-use campaign on Indeed.

   API call for single-use campaign:

   

   API call to create a campaign

   Single-use campaign created on Indeed:

   

   Single-use campaign created on Indeed

Create an objective-based campaign

This example creates an objective-based campaign that targets a specific amount of scheduled interviews.

1. Use an access token with the required scopes for an objective-based campaign.

   Create an objective-based campaign

   scope	employer_access employer.advertising.campaign

2. Get the source ID for the jobs in the objective-based campaign.

   To get the job source ID, get employer account information. An employer can have more than one job source ID, one for each website or domain. The jobSourceList.id response field contains the job source ID for each site.

3. Create the interview objective campaign.

   API details for the interview objective campaign:

   Create interview objective campaign

   API URL	https://apis.indeed.com/ads/v1/campaigns (Sponsored Jobs API reference)
   Request type	POST
   Content type	application/json
   Auth	OAuth 2.0 bearer token

   Sample request for the interview objective campaign:

   {
     "name": "XXX SCHEDULED_INTERVIEWS",
     "status": "PAUSED",
     "trackingToken": "indeed_chi",
     "jobsSourceId": "[Your jobsSourceId from Step 2]",
     "jobsToInclude": "ALL",
     "jobsQuery": "Java",
     "jobsTitle": "software engineer",
     "jobsCompany": "Indeed",
     "jobsLocation": "Austin",
     "jobsLocationRadius": 5,
     "fixedEndDate": "2023-10-20",
     "budgetOnetimeLimit": 1000,
     "objective": {
       "objectiveType": "SCHEDULED_INTERVIEWS",
       "target": 77
     }
   }

   Sample response for interview objective campaign:

   {
     "meta": {
       "status": 201,
       "errors": null,
       "rootLocation": "https://apis.indeed.com/ads",
       "perPage": null,
       "links": [{
         "rel": "Campaign Info",
         "href": "/v1/campaigns/f261xxxxxxxx6567"
       }]
     },
     "data": {
       "campaignId": "f261xxxxxxxx6567"
     }
   }

4. View interview campaign on Indeed.

   

   Interview campaign created on Indeed

   

   Interview target setting of interview campaign created on Indeed

Create recurring campaign

This example creates a recurring campaign that runs for six months and sponsors manager jobs in three locations with a budget of $1500 per month.

1. Use an access token with the required scopes.

   Create recurring campaign

   scope	employer_access employer.advertising.campaign

2. Get the source ID for the jobs in the recurring campaign.

   To get the job source ID, get employer account information. An employer can have more than one job source ID, one for each website or domain. The jobSourceList.id response field contains the job source ID for each site.

3. Create the recurring campaign.

   API details for the recurring campaign:

   Create recurring campaign

   API URL	https://apis.indeed.com/ads/v1/campaigns (Sponsored Jobs API reference)
   Request type	POST
   Content type	application/json
   Auth	OAuth 2.0 bearer token

   Sample request for the recurring campaign:

   {
     "name": "Test Campaign Recurring",
     "status": "PAUSED",
     "trackingToken": "MyTrackingToken",
     "jobsSourceId": "[Your jobsSourceId from Step 2]",
     "jobsToInclude": "QUERY",
     "jobsQuery": "(city:Aberdeen OR city:Glasgow OR city:London) AND title: Manager",
     "budgetMonthlyLimit": 1500,
     "startDate": "2021-09-01",
     "fixedEndDate": "2022-04-01"
   }

   Sample response for recurring campaign:

   {
     "meta": {
       "status": 201,
       "errors": null,
       "rootLocation": "https://apis.indeed.com/ads",
       "perPage": null,
       "links": [{
         "rel": "Campaign Info",
         "href": "/v1/campaigns/52fxxxxxxxxx310"
       }]
     },
     "data": {
       "campaignId": "52fxxxxxxxxx310"
     }
   }

4. View the recurring campaign on Indeed.

   API call for the recurring campaign:

   

   API call for a recurring campaign created on Indeed

   Recurring campaign created on Indeed:

   

   Recurring campaign created on Indeed

Edit recurring campaign

This example finds and updates a campaign and adds another location. You can also use this endpoint to start or pause campaigns, rename campaigns, and change the tracking token for a campaign. For more information, see the Sponsored Jobs API reference.

1. Use an access token with the required scopes for updates.

   Edit recurring campaign

   scope	employer_access employer.advertising.campaign

2. List your campaigns and IDs to get the campaign ID for the recurring campaign.

   API details for recurring campaign updates:

   Update recurring campaign

   API URL	https://apis.indeed.com/ads/v1/campaigns (Sponsored Jobs API reference)
   Request type	GET
   Content type	application/json
   Auth	OAuth 2.0 bearer token

   Request parameters for recurring campaign updates:

   Update recurring campaign request parameters

   Key	Value
   perPage	10
   status	PAUSED
   type	SOURCE

   Sample response for recurring campaign updates:

   "meta": {
     "status": 200,
     "errors": null,
     "rootLocation": "https://apis.indeed.com/ads",
     "perPage": 10,
     "links": [{
         "rel": "'Test Campaign Single-use' Info",
         "href": "/v1/campaigns/c8bxxxxxxxxx449"
       },
       {
         "rel": "'Test Campaign Recurring' Info",
         "href": "/v1/campaigns/52fxxxxxxxxx310"
       }
     ]
   },
   "data": {
     "Campaigns": [{
         "Name": "Test Campaign Single-use",
         "Id": "c8bxxxxxxxxx449",
         "Status": "PAUSED"
       },
       {
         "Name": "Test Campaign Recurring",
         "Id": "52fxxxxxxxxx310",
         "Status": "PAUSED"
       }
     ]
   }

3. Update the campaign query.

   In the jobsQuery field, pass a query using the indexed jobs query format.

   API details for the campaign query update:

   Update campaign query

   API URL	https://apis.indeed.com/ads/v1/campaigns/<YourCampaignIdFromStep2} (Sponsored Jobs API reference)
   Request type	PATCH
   Content type	application/json
   Auth	OAuth 2.0 bearer token

   Sample request for the campaign query update:

   {
     "jobsToInclude": "QUERY",
     "jobsQuery": "(city:Aberdeen OR city:Glasgow OR city:London OR city:Birmingham) AND title: Manager"
   }

   Sample response for campaign query update:

   {
     "meta": {
       "status": 200,
       "errors": null,
       "rootLocation": "https://apis.indeed.com/ads",
       "perPage": null,
       "links": [{
           "rel": "up",
           "href": "/v1/campaigns"
         },
         {
           "rel": "Campaign Info",
           "href": "/v1/campaigns/52fxxxxxxxxx310"
         },
         {
           "rel": "Traffic Statistics",
           "href": "/v1/campaigns/52fxxxxxxxxx310/stats"
         }
       ]
     },
     "data": {
       "campaignId": "52fxxxxxxxxx310"
     }
   }

4. View update campaign query on Indeed.

   API call for recurring campaign update:

   

   API call to edit a recurring campaign

   Updated recurring campaign on Indeed:

   

   Recurring campaign updated on Indeed

Change campaign budget

This example finds and updates a campaign and increases the monthly budget by $250, from $1500 to $1750.

1. Use an access token with the required scopes for a campaign budget update.

   Change campaign budget

   scope	employer_access employer.advertising.campaign

2. Get the ID of the campaign budget to update.

   To list campaigns, see get campaign ID for recurring campaign.

3. Update the campaign budget.

   API details for the campaign budget update:

   Update campaign budget

   API URL	https://apis.indeed.com/ads/v1/campaigns/{YourCampaignIdFromStep2}/budget (Sponsored Jobs API reference)
   Request type	PATCH
   Content type	application/json
   Auth	OAuth 2.0 bearer token

   Sample request for the campaign budget update:

   {
     "budgetMonthlyLimit": "1750"
   }

   Sample response for campaign budget update:

   {
     "meta": {
       "status": 200,
       "errors": null,
       "rootLocation": "https://apis.indeed.com/ads",
       "perPage": null,
       "links": [{
           "rel": "up",
           "href": "/v1/campaigns"
         },
         {
           "rel": "Campaign Info",
           "href": "/v1/campaigns/52fxxxxxxxxx310"
         },
         {
           "rel": "Traffic Statistics",
           "href": "/v1/campaigns/52fxxxxxxxxx310/stats"
         }
       ]
     },
     "data": {
       "campaignId": "52fxxxxxxxxx310"
     }
   }

4. View campaign budget on Indeed.

   API call to update campaign budget:

   

   API call to update a campaign budget

   Example updated campaign budget:

   

   Updated campaign budget on Indeed

Change campaign timeframe

This example locates and extends the time frame of a one-time campaign by two weeks.

1. Use access token with scopes for campaign timeframe.

   Change campaign timeframe

   scope	employer_access employer.advertising.campaign

2. Get ID of campaign timeframe.

   To list campaigns, see get campaign ID for recurring campaign.

3. Update campaign dates.

   API details for campaign timeframe:

   Update campaign dates

   API URL	https://apis.indeed.com/ads/v1/campaigns/{YourCampaignIdFromStep2}/budget (Sponsored Jobs API reference)
   Request type	PATCH
   Content type	application/json
   Auth	OAuth 2.0 bearer token

   Sample request for campaign timeframe:

   {
     "fixedEndDate": "2021-09-30"
   }

   Sample response for campaign timeframe:

   {
     "meta": {
       "status": 200,
       "errors": null,
       "rootLocation": "https://apis.indeed.com/ads",
       "perPage": null,
       "links": [{
           "rel": "up",
           "href": "/v1/campaigns"
         },
         {
           "rel": "Campaign Info",
           "href": "/v1/campaigns/c8bxxxxxxxxx449"
         },
         {
           "rel": "Traffic Statistics",
           "href": "/v1/campaigns/c8bxxxxxxxxx449/stats"
         }
       ]
     },
     "data": {
       "campaignId": "c8bxxxxxxxxx449"
     }
   }

4. View campaign timeframe on Indeed.

   API call to update campaign timeframe:

   

   API call to update a campaign timeframe

   Example updated campaign end date:

   

   Updated end date on Indeed

View jobs in campaign

This example gets detailed information for jobs sponsored by a campaign.

1. Use access token with scopes for campaign jobs.

   View jobs in campaign

   scope	employer_access employer.advertising.campaign

2. Get ID of campaign to update. To list campaigns, see get campaign ID for recurring campaign.

3. Get first page of jobs sponsored by campaign.

   API details for jobs:

   Get first page of jobs sponsored by campaign

   API URL	https://apis.indeed.com/ads/v1/campaigns/{YourCampaignIdFromStep2}/jobDetails (Sponsored Jobs API reference)
   Request type	GET
   Content type	application/json
   Auth	OAuth 2.0 bearer token

   Sample request for update campaign:

   Request parameters for update campaign:

   Update campaign request parameters

   Key	Value
   start	0
   perPage	3

   Sample response for update campaign:

   {
     "meta": {
       "status": 200,
       "errors": null,
       "rootLocation": "https://apis.qa.indeed.tech/ads",
       "perPage": 3,
       "links": null
     },
     "data": {
       "entries": [{
           "jobKey": "839d4e5b2b8ca2a6",
           "refNum": "267",
           "title": "Experienced Driver",
           "location": "London"
         },
         {
           "jobKey": "4191b62313a544aa",
           "refNum": "259",
           "title": "Branch Foreman",
           "location": "London"
         },
         {
           "jobKey": "2977cb389f748f51",
           "refNum": "305",
           "title": "Trainee Manager",
           "location": "London"
         }
       ],
       "hash": 964409796
     }
   }

4. Get the remaining pages.

   Use the same request format for later pages. To fetch the next page, set start to the previous start plus the previous perPage, and keep perPage the same. For example, if the last page used start = 10 and perPage = 5, request the next page with start = 15 and perPage = 5. To get all jobs sponsored by a campaign, continue fetching consecutive pages until one of these happens:

   • The perPage meta field in the response differs from the requested perPage. This usually means that you reached the last page.

     perPage has a maximum of 500, so if the requested perPage is greater than 500, a different value in the response does not always mean that you reached the last page.

   • The hash field in the response differs from the value on the previous page. This means the jobs list changed while you were reading it. Pause for one minute, and then restart from start = 0.

How-to guides for reports

Report on campaign performance

This example requests performance data for a campaign over a three-day period.

The example returns both an aggregated view and a per-day breakdown.

Use access token with scopes for campaign performance report

Use access token with scopes for campaign performance report

scope	employer_access employer.advertising.campaign_report.read

Get the campaign ID for campaign performance report

To list campaigns, see get campaign ID for recurring campaign.

Get campaign statistics

API details for campaign performance report

Campaign performance report

API URL	https://apis.indeed.com/ads/v1/campaigns/{YourCampaignIdFromStep2}/stats (Sponsored Jobs API reference)
Request type	GET
Content type	application/json
Auth	OAuth 2.0 bearer token

Request parameters for campaign performance report

Campaign performance report request parameters

Key	Value
startDate	2021-07-16
endDate	2021-07-31
merge	TRUE Set this field to FALSE to get a per-day breakdown.

API response (Merge = TRUE)

{
  "meta": {
    "status": 200,
    "errors": null,
    "rootLocation": "https://apis.indeed.com/ads",
    "perPage": null,
    "links": [{
      "rel": "up",
      "href": "/v1/campaigns//b0fxxxxxxxxx327/stats"
    }]
  },
  "data": {
    "Name": "TMN test UK - Target Applies",
    "Id": "/b0fxxxxxxxxx327",
    "StartDate": "2021-07-22",
    "EndDate": "2021-07-24",
    "Clicks": 989,
    "Impressions": 8384,
    "Conversions": 217,
    "CurrencyCode": "USD",
    "Cost": 598.69,
    "OrganicClicks": 35,
    "OrganicImpressions": 303,
    "Applystarts": 320,
    "OrganicApplystarts": 18
  }
}

API response (Merge = FALSE)

{
  "meta": {
    "status": 200,
    "errors": null,
    "rootLocation": "https://apis.indeed.com/ads",
    "perPage": 10,
    "links": [
      {
        "rel": "up",
        "href": "/v1/campaigns//b0fxxxxxxxxx327/stats"
      }
    ]
  },
  "data": {
    "entries": [
      {
        "Name": "TMN test UK - Target Applies",
        "Id": "/b0fxxxxxxxxx327",
        "Date": "2021-07-22",
        "Clicks": 373,
        "Impressions": 3238,
        "Conversions": 83,
        "CurrencyCode": "USD",
        "Cost": 258.76,
        "OrganicClicks": 22,
        "OrganicImpressions": 226,
        "Applystarts": 125,
        "OrganicApplystarts": 9
      },
      {
        "Name": "TMN test UK - Target Applies",
        "Id": "/b0fxxxxxxxxx327",
        "Date": "2021-07-23",
        "Clicks": 318,
        "Impressions": 2665,
        "Conversions": 74,
        "CurrencyCode": "USD",
        "Cost": 178.28,
        "OrganicClicks": 7,
        "OrganicImpressions": 42,
        "Applystarts": 104,
        "OrganicApplystarts": 4
      },
      {
        "Name": "TMN test UK - Target Applies",
        "Id": "/b0fxxxxxxxxx327",
        "Date": "2021-07-24",
        "Clicks": 298,
        "Impressions": 2481,
        "Conversions": 60,
        "CurrencyCode": "USD",
        "Cost": 161.65,
        "OrganicClicks": 6,
        "OrganicImpressions": 35,
        "Applystarts": 91,
        "OrganicApplystarts": 5
      }
    ]
  }
}

API call for campaign performance report

API call for a campaign performance report call

How-to guides for account management

Get employer account information

Get the employer's ID, contact information, and more.

1. Use access token with scopes for employer account.

   Get employer account information

   scope	employer_access employer.advertising.account.read

2. Query the account endpoint.

   API details for employer account:

   API details for employer account

   API URL	https://apis.indeed.com/ads/v1/account (Sponsored Jobs API reference)
   Request type	GET
   Content type	application/json
   Auth	OAuth 2.0 bearer token

   Sample response for employer account:

   {
     "meta": {
       "status": 200,
       "errors": null,
       "rootLocation": "https://apis.indeed.com/ads",
       "perPage": null,
       "links": null
     },
     "data": {
       "employerId": "a2973d75fd4xxxxxxx748785257446e7",
       "jobSourceList": [
         {
           "id": "a284xxxxxxx1c1f9",
           "siteName": "MyCompany"
         }
       ],
       "contact": "",
       "company": "My Company Name",
       "id": "4958xxxxxxx3732",
       "email": "myEmailAddress@indeed.com"
     }
   }

Get subaccount information

Get a detailed list of subaccounts for a specific master account.

1. Use access token with scopes for subaccount information.

   Do not include the employer parameter when getting the access token for this operation.

   Get subaccount information

   scope	employer.advertising.subaccount.read

2. Query the subaccounts endpoint.

   API details to query subaccounts endpoint:

   API details for query subaccounts

   API URL	https://apis.indeed.com/ads/v1/subaccounts (Sponsored Jobs API reference)
   Request type	GET
   Content type	application/json
   Auth	OAuth 2.0 bearer token

   Sample response to query subaccounts endpoint:

   {
     "meta": {
       "status": 200,
       "errors": null,
       "rootLocation": "https://apis.indeed.com/ads",
       "perPage": 2,
       "links": {
         "rel": "next",
         "href": "/V1/campaigns/3141xxxxxxxxx793"
       }
     },
     "data": {
       "SubAccountList": {
         "id": "3141xxxxxxxxx793",
         "employerId": "4bc39xxxxxxxxx8efbc8486",
         "company": "MyTestCompany",
         "email": "example@mytestcompany.com"
       }
     }
   }

Create a subaccount

Add a subaccount to a master account.

1. Use access token with scopes to create subaccount.

   Do not include the employer parameter when retrieving the access token for this operation.

   Create subaccount

   scope	employer.advertising.subaccount

2. Create the subaccounts endpoint.

   API details to create subaccounts endpoint:

   API details for create subaccounts

   API URL	https://apis.indeed.com/ads/v1/subaccounts (Sponsored Jobs API reference)
   Request type	POST
   Content type	application/json
   Auth	OAuth 2.0 bearer token

   Sample request to create subaccounts endpoint:

   {
     "email": "testsubaccount@mytestcompany.com",
     "currencyCode": "USD",
     "language": "en",
     "employeeCount": "1-49",
     "company": "MyTestCompany2"
   }

   Sample response for subaccounts creation:

   {
     "meta": {
       "status": 200,
       "errors": null,
       "rootLocation": "https://apis.indeed.com/ads",
       "perPage": null,
       "links": null
     },
     "data": {
       "id": "31xxxxxxxxx794",
       "employerId": "4bc39xxxxxxxxx8efbc8486",
       "company": "MyTestCompany2",
       "email": "testsubaccount@mytestcompany.com",
     }
   }

Get an account budget

Get the account's monthly budget.

1. Use access token with scopes for account budget:

   scope	employer_access employer.advertising.account.read

2. Get the account budget endpoint. API details to get account budget:

   API URL	https://apis.indeed.com/ads/v1/account/budget (Sponsored Jobs API reference)
   Request type	GET
   Content type	application/json
   Auth	OAuth 2.0 bearer token

   Sample response for get account budget:

   If no budget is set, the jobsMonthlyBudget response field returns null.

   {
     "meta": 
     { 
       "status": 200,
       "errors": null,
       "rootLocation": "https://apis.indeed.com/ads",
       "perPage": null,
       "links": 
         [
           {
            "rel": "up",
            "href": "/v1/account"
           }
         ],
       "data": 
         {
           "jobsMonthlyBudget": null
         }
     }
   }

Set an account budget

Update the account's monthly budget.

1. Use access token with scopes to set an account budget.

   scope	employer_access employer.advertising.account

2. Query the account budget endpoint.

   Set an account budget: API details:

   API URL	https://apis.indeed.com/ads/v1/account/budget (Sponsored Jobs API reference)
   Request type	PATCH
   Content type	application/json
   Auth	OAuth 2.0 bearer token

   Set an account budget: Sample request:

   { "jobsMonthlyBudget": 20000 }

   Set an account budget: Sample response:

   {
     "meta": {
     "status": 200,
     "errors": null,
     "rootLocation": "https://apis.indeed.com/ads",
     "perPage": null,
     "links": [
       {
         "rel": "up",
         "href": "/v1/account"
       }
     ],
     "data": ""
   }

   After you make this update and call Get an Account Budget, you receive the following response:

   {
     "meta":
     {
       "status": 200,
     "errors": null,
     "rootLocation": "https://apis.indeed.com/ads",
     "perPage": null,
     "links": [
       "rel": "up",
       "href": "/v1/account"
       ],
     "data":
       {
         "jobsMonthlyBudget": 20000.00
       }
     }
   }

   Jobs monthly budget setting in Indeed UI:

   

   Monthly budget setting in Indeed UI

How-to guides for API quota usage

Get advertiser's API quota usage

Get the advertiser's Sponsored Jobs API usage, quota, and sponsored job spend for the given month.

The API usage count does not show data for the current day. The spend amount represents the total spend up to the current date for the current month, or the total spend for completed months.

1. Use access token with scopes for API quota usage details.

Get advertiser's API quota usage

scope	employer_access employer.advertising.account.read

2. Call the API quota usage endpoint to get API quota usage:

API details for get advertiser's API quota usage

API URL	https://apis.indeed.com/ads/v1/apiquotausage (Sponsored Jobs API reference)
Request type	GET
Content type	application/json
Auth	OAuth 2.0 bearer token

Request parameters for API quota usage:

Get advertiser's API quota usage request parameters

Key	Value
monthYear	Month of quota usage data to retrieve, in MMyyyy format (for example, 122024 for December 2024). Must be between December 2024 (122024) and the current month, inclusive. Optional. Default is the current month.

Sample response for GET API quota usage:

  {
    "meta": {
      "status": 200,
      "errors": null,
      "rootLocation": "https://apis.indeed.com/ads",
      "perPage": null,
      "links": null
    },
    "data": {
      "mmyyyy": "112024",
      "apiQuota": 1500,
      "sponsoredJobsSpendAmount": 3000,
      "currencyCode": "USD",
      "apiUsage": [
        {
          "requestsCount": 1000
        }
      ]
    }
  }

Recommendations and guidelines

Prepare for eventual consistency

The API uses an eventual consistency model. For example, after you call POST /v1/campaigns to create a campaign, GET /v1/campaigns/{campaignId} might not return the new campaign for a brief period.

To handle eventual consistency, do not read a resource immediately after you create or update it. A successful response (200, 201, or another success code) confirms that Indeed persisted your changes — you do not need a follow-up GET to verify.

If you must read the resource right after a create or update, add a retry to wait for the change to become visible.

Ensure compatibility with API changes

Indeed can release backwards-compatible changes to the Sponsored Jobs API at any time without advance notice. Backwards-compatible changes include:

• Adding response fields.
• Reordering response fields.
• Updating error descriptions.
• Supporting new currencies and objective types.

Your app must follow these guidelines so backwards-compatible changes don't cause issues:

• Ignore unknown properties in JSON responses.
• Accept properties in any order in JSON responses.
• Use the type property to distinguish between errors, not the description.

Also, if your app works with employer accounts that your app does not solely manage, your app can encounter resources that another third-party app or Indeed for Employers created. Your app must handle these situations:

• Getting or updating campaigns that another app created might return the INCOMPATIBLE_API_VERSION error.
• Campaigns and subaccounts that another app created might use currency codes that your app does not support. Your app must handle any ISO 4217 currency code.
• Campaigns that another app created might use objective types that your app does not support. Your app must include fallback logic for unexpected objective types.

If you develop in Java, the popular Jackson library fails on unknown properties by default. To change this behavior, set @JsonIgnoreProperties(ignoreUnknown = true), which disables DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES.

FAQs and troubleshooting

FAQs

Indeed does not provide a sandbox environment. You can read data from Indeed APIs in production with no cost or impact to your account. When testing create and update operations, create test campaigns in a paused state (status=paused) to prevent spending.

See Indexed jobs query format.

To clear an account budget, contact your client success representative.

Troubleshoot common errors

This topic describes errors that the Sponsored Jobs API returns. For errors that the authorization endpoints, such as https://apis.indeed.com/oauth/v2/tokens, return, see Troubleshoot authorization errors.

An unsuccessful HTTP status code, such as 400 through 599, indicates that the request failed. The response body contains further details. For example, calling Sponsored Jobs API without an access token results in the following response:

{
  "meta": {
    "status": 401,
    "errors": [{
      "type": "INVALID_TOKEN",
      "description": "Couldn't find access token in the request. The Authorization header is missing or incorrectly formatted."
    }],
    "rootLocation": "https://apis.indeed.com/ads",
    "perPage": null,
    "links": null
  },
  "data": null
}

The errors array in the meta response field contains the error. Every error has a type and a human-readable description. This table describes the common error types.

Because the request path was not prefixed with /ads, the response indicates that the request could not be routed to the Sponsored Jobs API. For example, instead of https://apis.indeed.com/v1/account, use https://apis.indeed.com/ads/v1/account.

{
  "fault": {
    "faultstring": "Unable to identify proxy for host: apis and url: /v1/account",
    "detail": {
      "errorcode": "messaging.adaptors.http.flow.ApplicationNotFound"
    }
  }
}

HTTP status codes

HTTP status	Error type	Description and common causes
400	DATE_RANGE_TOO_LONG	Indicates that the startDate and endDate request parameter values were too far apart. endDate can be, at most, 366 days later than startDate. If you need data for a longer date range, split the request into batches of no more than 366 days. Only GET /v1/campaigns/{campaignId}/stats and GET /v1/campaigns/{campaignId}/stats/entryDates return this error.
400	INCOMPATIBLE_API_VERSION	Your app gets or updates a resource that is incompatible with the Sponsored Jobs API version that your app invokes. This error occurs when an entity outside your app creates or modifies the resource. This error is reserved for potential future use and is not returned.
400	INVALID_ADVERTISEMENT_ID	The campaign ID included in the request was truncated, included unexpected characters or was otherwise malformed.
400	INVALID_REQUEST	A problem occurred with one of the request parameters: A required parameter was missing. A parameter had an invalid value. A parameter that is no longer supported was included in the request. The request included a combination of parameters that can't be used together. The description field usually contains the name of the problematic parameter and a more detailed error message. For example: { "meta": { "errors": [{ "type": "INVALID_REQUEST", "description": "jobsToInclude: One of \"all\", \"query\"" }] } } Unlike other error types, the meta.errors array can contain multiple INVALID_REQUEST errors, one for each request parameter with a problem.
400	UNACCEPTED_PARAMETER	Specifying the subaccount to access using the advertiserId parameter is no longer supported. Instead, include the employer parameter when requesting the access token. Note that the employer IDs accepted by the employer parameter are different from the values accepted by the legacy advertiserId parameter. The GET /v1/subaccounts endpoint now returns the employer IDs of your subaccounts along with the legacy IDs.
400	NOT_MASTER_ACCOUNT	This API endpoint can only be called with a master account. For now, this error is only returned from GET /v1/subaccounts and POST /v1/subaccounts.
401	INVALID_TOKEN	Request did not include a valid access token: The Authorization header was missing or malformed. Be sure to send the access token in the Authorization HTTP header and prefix the value with the word Bearer and a space. For example, if the access token was XYZ, then your request should include Authorization: Bearer XYZ header. The access token was malformed. If you're testing the API by constructing HTTP requests manually, check that you didn't happen to leave out or include extra characters at the beginning or the end of the access token when copying it to your request. The access token has expired. Access tokens are only valid for one hour (3600 seconds). After that, you need to retrieve another access token using your client credentials (2-legged OAuth) or a refresh token (3-legged OAuth).
403	EMPLOYER_ACCESS_TOKEN_NOT_ALLOWED	This API endpoint can't be accessed with an access token representing an employer. This might be because: This API endpoint can only be called with a master account. Omit the employer parameter when requesting the access token for this operation. For now, this error is only returned from GET /v1/subaccounts and POST /v1/subaccounts. You are calling the legacy Sponsored Jobs API endpoint instead of the new API endpoint. Be sure to use the new endpoint (https://apis.indeed.com/ads).
403	INSUFFICIENT_SCOPE	The access token was valid but didn't have the scope required for this API endpoint. If you are using the client credentials grant type (2-legged OAuth): You didn't include the required scope in the scope parameter when calling https://apis.indeed.com/oauth/v2/tokens. Return to the OAuth steps to request an access token that includes the required scope. See scopes to find the required scope for the endpoints you're calling. The app's account hasn't been granted admin access to this employer. You can verify the level of access your app has on Manage access. If you are using the authorization code grant type (3-legged OAuth): You didn't include the required scope in the scope parameter when redirecting the user to https://secure.indeed.com/oauth/v2/authorize. See scopes to find the required scope for the endpoints you're calling. The user didn't grant the required scope your app, or the user hasn't been granted admin access to the employer. You can distinguish between these conditions by looking at the consented_scope response field returned from https://apis.indeed.com/oauth/v2/tokens. The field contains all permissions granted by the user to your app, regardless of their level of access to the employer. Note that GET /v1/account is a special case: To get the details of an employer, including one of your subaccounts, the required scope is employer.advertising.account.read and the access token must represent the employer. To get the details of your master account itself, the required scope is employer.advertising.subaccount.read (sic) and the access token must not associate user account with employer account.
403	LEGACY_ACCESS_TOKEN_NOT_ALLOWED	Sponsored Jobs API no longer supports access tokens that you get through legacy OAuth endpoints. For the updated endpoints, see Integrate with Indeed and call APIs.
403	NOT_EMPLOYER_ACCESS_TOKEN	The opposite of the EMPLOYER_ACCESS_TOKEN_NOT_ALLOWED above. This endpoint requires an access token that associates a user account with an employer account. That is, you must specify the employer parameter when requesting the access token. You must do this for most Sponsored Jobs API endpoints.
404	RESOURCE_NOT_FOUND	Indicates that there was a problem with the request URL: The requested campaign does not exist, or belongs to a different employer. Be sure to use an access token that associates a user account with an employer account that owns the requested campaign. No campaign statistics are available for the requested date. The campaign was created after the requested date, the campaign wasn't active on the requested date or, in case of a recent date, the data is still being processed. The request path was misspelled. Verify the correct URL pattern in the API reference documentation.
500	Any (usually INTERNAL_SERVER_ERROR)	Unexpected error. The problem is sometimes temporary. The same request can succeed after retrying. If retrying the request does not help, a problem with parsing the request might have occurred. Make sure that all the required parameters are present and that all parameters are correctly formatted. If you try to use an access token obtained with the client credentials grant type (2-legged OAuth) with the legacy Sponsored Jobs API endpoint, you also see INTERNAL_SERVER_ERROR. Be sure to use the https://apis.indeed.com/ads endpoint.

Troubleshoot OAuth errors

See Troubleshoot OAuth errors.

 

Was this page helpful?