Skip to main content

List employer campaigns and statuses

GET 
/v1/campaigns

Lists an employer's campaigns and their statuses. Results might be paginated.

Example: List active campaigns, up to 100 per page:

https://apis.indeed.com/ads/v1/campaigns?status=ACTIVE&perPage=100
OAuth scopeAccess token type
employer.advertising.campaign.read

Access token that represents an employer.

Request​

Query Parameters

    perPage integer

    Default value: 30

    Maximum number of campaigns returned in the response. The response might contain fewer campaigns than the requested maximum, even if more results are available. Be sure to always check the response for the presence of another page of results. Maximum limit is 500 campaigns in a single page.

    start string

    Position within a paginated response. The value corresponding to the next page of results is included in the response if more results are available.

    status string

    Possible values: [ACTIVE, DELETED, PAUSED]

    Campaign status. To filter the results by campaign status, pass one of ACTIVE, DELETED or PAUSED. Defaults to returning campaigns in all statuses.

    type string

    Possible values: [SOURCE, HOSTED]

    Job type. To filter the results by the type of job sponsored by the campaign, pass either SOURCE (jobs gathered from the web, or sent to Indeed using an XML feed) or HOSTED (jobs posted using the Post a Job page). Defaults to returning campaigns with either type of job.

    fields string

    Comma-separated list of fields to include in the response. Valid values are Id, Name, Status, NonSpendingReasons, Type, CurrencyCode, TrackingToken, StartDate, FixedEndDate, TargetEndDate, BudgetOnetimeLimit, BudgetMonthlyLimit, FundingSource, SponsorshipPlan, and DailyAvgBudgetPerJob. Default is Id,Name,Status.

    campaignIds string

    Comma-separated list of campaignIds for which to list campaigns. Supports up to 50 campaign IDs. Supports only the fields query parameter.

Responses​

List campaigns. If no matching campaigns are found and you omit the campaignIds parameter, returns an empty data.Campaigns array and the HTTP 200 status code.

The results might be paginated. If more results are available, the meta.links array contains an item with the "rel": "next" property. Append the value of the href property to the base URL to retrieve the next page of results.

Note: Currently the next URL won't include other parameters except the start parameter. If you used non-default values for perPage, status, or type, append them to the URL. This requirement might change in future API versions.

Schema

    meta

    object

    Response-related metadata.

    status int32

    HTTP status code of the response.

    errors

    object[]

    Any errors that prevented successful processing of the request. If there were no errors, the value is null.

  • Array [

    • type string

    Name of the error.

    description string

    Human-readable description of the problem.

  • ]

    • rootLocation string

    Base URL of the Sponsored Jobs API.

    perPage int32

    For endpoints that return paginated results, the effective maximum number of entries returned on one page. The value may be smaller than the maximum you requested with the perPage parameter. If the endpoint returns a single result or doesn't paginate, the value is null.

    links

    object[]

    Resources related to the requested resource.

  • Array [

    • rel string

    The relationship between the requested resource and the related resource. These values are commonly used:

    • up: The related resource is a collection that contains the requested resource, or an entity that the requested resource is attached to.
    • next: The next page of entries in a paginated result.
    • prev: The previous page of entries in a paginated result.

    However, the value may also be an arbitrary string describing the relationship, such as Campaign Info.

    href string

    Endpoint URL of the related resource. Can contain query string parameters. To get the complete URL, append the href to rootLocation.

  • ]

    • objective

    object

    Specifies the hiring goals that the campaign is intended to achieve, and makes the campaign into an objective-based campaign. The value is a JSON object with an objectiveType field specifying the campaign objective, and for some objective types, a target field identifying the specific goal metric.

    For example, if the goal of the campaign is to supply 10 apps, set the objective to:

    {
      "objectiveType": "TARGET_APPLICATIONS",
      "target": 10
    }

    You can add an objective to a campaign that doesn't have one, and change the target value of an objective. However, you cannot remove an objective or change its objectiveType.

    objectiveType

    string

    Possible values: [BALANCE, MAXIMUM, QUICK, TARGET_APPLICATIONS, TARGET_COST_PER_APPLICATION, SCHEDULED_INTERVIEWS]

    The campaign objective. The available values are:

    • BALANCE: Get the most total applications for your budget, while balancing across jobs.
    • MAXIMUM: Get the most total applications for your budget, without balancing clicks across.
    • QUICK: Five day campaign with higher budget for faster results. Sponsored Jobs API does not currently support creating or modifying campaigns with this objective. However, the Sponsored Jobs API does allow for retrieving campaign reports for campaigns with this objective type (these campaigns would have been created using Indeed for Employers).
    • TARGET_APPLICATIONS: Aim to reach the number of applications specified by target. When the target number of applications is hit, spend on these jobs is significantly reduced and allocated elsewhere.
    • TARGET_COST_PER_APPLICATION: Aim to keep the cost per application below the number specified by target.
    • SCHEDULED_INTERVIEWS: Send screened candidates straight to interview. Aim to reach the number of interviews specified by target. This objective requires an active Indeed Hiring Platform subscription, and should only be used when the customer is prepared to create hiring events for the included jobs.

    Campaigns created outside your app can use latest objective types. See Ensure compatibility with API changes that your app does not support yet. To handle unexpected objectiveType values, ensure your app has fallback logic.

    any

    data

    object

    Campaigns

    object[]

  • Array [

    • Name string

    Possible values: non-empty and <= 250 characters

    Campaign name. Use to identify the campaign later. The name must be unique within your employer account.

    Id string

    Campaign ID. Automatically generated when the campaign is created.

    Status string

    Possible values: [ACTIVE, DELETED, PAUSED]

    Default value: ACTIVE

    Campaign status. PAUSED creates a campaign that does not start sponsoring jobs until you manually enable it, or temporarily stops a campaign from sponsoring jobs.

    NonSpendingReasons

    object[]

    List of reasons that are currently preventing the campaign from sponsoring jobs.

  • Array [

    • type string

    Possible values: [BEFORE_START_DATE, AFTER_END_DATE, ACCOUNT_MONTHLY_BUDGET_HIT, MONTHLY_BUDGET_HIT, ONETIME_BUDGET_HIT, JOB_SOURCE_NOT_VERIFIED, BILLING_PENDING, USER_PAUSED_CAMPAIGN, USER_DELETED_CAMPAIGN, TARGET_APPLICATIONS_HIT, OTHER]

    Identifier for the problem. Value is:

    • BEFORE_START_DATE: The current date in US Central Time is before the campaign start date.
    • AFTER_END_DATE: The current date in US Central Time is on or after the campaign end date.
    • ACCOUNT_MONTHLY_BUDGET_HIT: The employer account has already spent its budget this month.
    • MONTHLY_BUDGET_HIT: The campaign has already spent its budget this month.
    • ONETIME_BUDGET_HIT: The campaign has already spent its budget.
    • JOB_SOURCE_NOT_VERIFIED: The job source hasn't been verified by Indeed yet.
    • BILLING_PENDING: The employer account doesn't have valid billing information.
    • USER_PAUSED_CAMPAIGN: Campaign has been paused, as requested.
    • USER_DELETED_CAMPAIGN: The campaign has been deleted as requested.
    • TARGET_APPLICATIONS_HIT: The campaign has already received the requested number of applications.
    • OTHER: Unknown reason.
    description string

    Human-readable description of the problem.

  • ]

    • Type string

    Possible values: [SOURCE, HOSTED]

    Type of job sponsored by the campaign. Either SOURCE (jobs gathered from the web, or sent to Indeed using an XML feed) or HOSTED (jobs posted using the Post a Job page).

    CurrencyCode string

    ISO 4217 currency code of the currency for the campaign's budget.

    TrackingToken string

    Possible values: <= 255 characters

    Click-tracking token appended to the job URL on sponsored clicks. Allows you to identify that the click is from Indeed, and identify the campaign that sponsored the click.

    BudgetOnetimeLimit number

    One-time budget limit for the campaign. You cannot set budgetOnetimeLimit and budgetMonthlyLimit at the same time.

    BudgetMonthlyLimit number

    Monthly budget limit for the campaign. You cannot set dailyAvgBudgetPerJob, budgetOnetimeLimit, and budgetMonthlyLimit at the same time.

    StartDate date

    Date when the campaign starts sponsoring jobs, in ISO 8601 YYYY-MM-DD format. Default is current date.

    The campaign starts sponsoring jobs at the start of the specified day in US Central Time (CT, US/Central). The start date is on or after the current date in CT. For example, if the startDate is 2021-01-15, the campaign starts sponsoring on January 15, 2021 at 0:00 AM CT. If the start date is not provided or is the current date, the campaign starts sponsoring immediately.

    Once the campaign is active and spending, you cannot update its startDate. If you wish to temporarily pause a campaign, set its status to PAUSED.

    FixedEndDate date

    Date before when the campaign must stop sponsoring jobs, even if it has remaining unspent budget. Follows the ISO 8601 YYYY-MM-DD format.

    A campaign with a one-time budget (budgetOnetimeLimit) always have either a fixedEndDate or a targetEndDate, but not both.

    A campaign with a monthly recurring budget (budgetMonthlyLimit) may optionally have a fixedEndDate. Monthly recurring campaigns default to sponsoring jobs until you manually pause or delete the campaign. These are called "evergreen" campaigns. To stop the campaign at the start of a specified day, specify fixedEndDate.

    The campaign stops sponsoring jobs at the start of the specified day in US Central Time (CT, US/Central). The fixedEndDate is atleast one day after the current date in CT, or the startDate of the campaign, if the campaign has one. For example, if the fixed end date is 2021-06-20, the campaign stops on June 20, 2021 at 0:00 AM CT.

    TargetEndDate date

    Date before when the campaign should stop sponsoring jobs, though it can continue sponsoring past the specified date if it has not spent its budget yet. Follows the ISO 8601 YYYY-MM-DD format.

    A campaign with a one-time budget (budgetOnetimeLimit) always have either a fixedEndDate or a targetEndDate, but not both. A campaign with a monthly recurring budget (budgetMonthlyLimit) cannot have a targetEndDate, only a fixedEndDate or no end date.

    The campaign targets the start of the specified day in US Central Time (CT, US/Central). The target end date is at least one day after the current date in CT, or the startDate of the campaign, if the campaign has one. For example, if the target end date is 2021-06-20, the campaign targets June 20, 2021 at 0:00 AM CT.

    FundingSource string

    Funding source for the campaign:

    • Bonus Sponsored Job Credits: Funded with Annual Deals bonus credits.
    • Budget: Funded with regular budget.

    Possible values: [Bonus Sponsored Job Credits, Budget].

    SponsorshipPlan string

    Sponsorship plan for campaigns funded by Annual Deals bonus credits. Returns "STANDARD" for standard campaigns, "PREMIUM" for premium plan campaigns, or "" (empty string) otherwise.

    Possible values: [PREMIUM, STANDARD, `` (empty string)]

    DailyAvgBudgetPerJob number

    Daily average budget for each job for the campaign. Returned only for campaigns that use the Average Daily Budget (ADB) model. You cannot set dailyAvgBudgetPerJob and budgetMonthlyLimit at the same time.

  • ]

Loading...

Was this page helpful?