Skip to main content

Create campaign

POST 
/v1/campaigns

Creates a sponsored jobs campaign.

Prerequisites:

  • Wait 2 to 3 hours after posting new jobs before creating a campaign.

  • Your employer account must be associated with a job source before you create a campaign.

  • Use GET /v1/account to list job sources for your account.

  • If no job sources are associated, contact Indeed Customer Support.

Your employer account must have valid billing information before the campaign can sponsor jobs.

OAuth scopeAccess token type
employer.advertising.campaign

Employer access token.

Request​

Body

required

Request body must be a JSON object that defines the campaign to create.

HTTP request headers

Include these HTTP request headers:

  • Content-Type: application/json

  • Accept: application/json

  • "idempotency-key": "<key>": Required to create average daily budget (ADB) campaigns. Provide a unique ID, such as e8908cde-8ccc-4500-8762-588ced4b4a88, to make create-campaign requests idempotent.

Objectives

You cannot set or change objectives for average daily budget (ADB) campaigns ( STANDARD and PREMIUM). You can add an objective to a campaign that does not have one and update its target, but you cannot remove the objective or change its objectiveType.

Required fields

Always specify name, jobsSourceName, and jobsToInclude.

Select the jobs to sponsor

  • Sponsor all jobs in the job source: Set jobsToInclude to ALL. Do not specify jobsQuery, jobsTitle, jobsCompany, jobsLocation, or jobsLocationRadius.

  • Sponsor a subset of jobs: Set jobsToInclude to QUERY. jobsQuery is required but jobsTitle, jobsCompany, and jobsLocation are optional.

Set the campaign budget and duration

  • Stop the campaign on a specific date: Specify budgetOnetimeLimit, then either fixedEndDate or targetEndDate. fixedEndDate stops sponsorship on that date even if budget remains. targetEndDate lets the campaign continue until the budget is spent. For an equal monthly budget, use budgetMonthlyLimit. In that case, you can use only fixedEndDate.

  • Run the campaign until you stop it: Specify budgetMonthlyLimit. Do not specify an end date.

Choose when the campaign starts

  • Start immediately: Default if you do not specify startDate or status.

  • Start on a future date: Specify startDate.

  • Start manually: Set status to PAUSED.

Optional features

  • Identify clicks from this campaign: Specify trackingToken.

  • Optimize for a hiring goal: Specify objective. The Sponsored Jobs API supports objective-based campaigns. See Creating an Effective Recruitment Funnel With Indeed Ads. You cannot set or change objectives for average daily budget (ADB) campaigns. All other Sponsored Jobs API campaigns must have an objective. If the employer does not provide one when creating a campaign, Sponsored Jobs API selects an appropriate objective automatically.

  • Sponsor jobs on the Trusted Media Network (TMN): Specify channels. After you create a campaign with a channel enabled or disabled, you cannot change that channel status.

See the model definition for field details and example values.

For example requests, see the How-to guides for campaign management.

    name string

    Possible values: non-empty and <= 250 characters

    Required.

    Campaign name.

    Use it to identify the campaign later.

    It must be unique within your employer account.

    status string

    Possible values: [ACTIVE, DELETED, PAUSED]

    Default value: ACTIVE

    Campaign status.

    ACTIVE starts the campaign.

    PAUSED keeps the campaign inactive or temporarily stops sponsorship.

    DELETED stops sponsorship.

    DELETED also hides the campaign from the default campaign-management view.

    trackingToken string

    Possible values: <= 255 characters

    Click-tracking token added to the job URL for sponsored clicks.

    Use it to identify clicks from Indeed.

    Use it to identify which campaign sponsored the click.

    jobsSourceId string

    Source ID that overrides jobsSource.

    It identifies the job source used by the campaign.

    Use the id from jobSourceList in GET /v1/account.

    If the employer account has no job sources, contact Indeed Customer Support.

    Each campaign supports only one jobsSourceId.

    If you have multiple job sources, create one campaign per source.

    jobsSourceName string

    Source name.

    ATS partners only.

    jobsToInclude string

    Possible values: [ALL, QUERY]

    Required.

    Use ALL or QUERY.

    ALL sponsors all jobs in the job source.

    ALL ignores and clears jobsQuery, jobsTitle, jobsCompany, jobsLocation, and jobsLocationRadius.

    QUERY sponsors only jobs that match your criteria.

    If you set multiple criteria, each job must match all criteria.

    If jobsToInclude is QUERY and you omit all criteria, the campaign currently sponsors all jobs in the job source.

    To avoid errors, provide at least one criterion or set jobsToInclude to ALL.

    jobsQuery string

    Jobs query.

    If set, the campaign sponsors only jobs that match these search terms.

    Supports Boolean expressions.

    See Indexed jobs query format.

    Applies only when jobsToInclude is QUERY.

    jobsTitle string

    Job title in the query.

    If set, the campaign sponsors only jobs with this title.

    Applies only when jobsToInclude is QUERY.

    jobsCompany string

    Company in the query.

    If set, the campaign sponsors only jobs from this hiring company.

    Applies only when jobsToInclude is QUERY.

    jobsLocation string

    Location in the query.

    If set, the campaign sponsors only jobs at or near this location.

    Applies only when jobsToInclude is QUERY.

    jobsLocationRadius int32

    Default value: 25

    Maximum distance from the job location to jobsLocation.

    Valid values are 5, 10, 15, 25, 50, and 100.

    Use miles for jobs in the United States and the United Kingdom.

    Use kilometers elsewhere.

    sponsorshipPlan string

    Possible values: [STANDARD, PREMIUM]

    Set sponsorshipPlan only for average daily budget (ADB) campaigns.

    Employers must provide it when creating an ADB campaign.

    If omitted, the campaign defaults to STANDARD.

    budgetCapType string

    Possible values: [ONETIME, MONTHLY, FLEXIBLE]

    Budget cap type.

    Valid values are ONETIME, MONTHLY, and FLEXIBLE.

    For ADB campaigns, set budgetOnetimeLimit when type is ONETIME.

    For ADB campaigns, set budgetMonthlyLimit when type is MONTHLY.

    Indeed optimizes spend toward your monthly or one-time budget target.

    If your budget limit is high, spend can exceed the recommended daily budget.

    avgDailyBudgetConfig

    object

    Average daily budget (ADB) campaign details.

    Required for ADB campaigns.

    adbBehaviour stringrequired

    Possible values: [AUTO]

    Required.

    Average daily budget (ADB) behavior.

    Valid value: AUTO.

    budgetBoostPercentage integer

    Possible values: <= 1500

    Boosts the base average daily budget (ADB) per job by a percentage.

    Use this field only for flexible ADB campaigns.

    Do not use it for monthly or one-time campaigns.

    New jobs added manually or through query resolution inherit the same percentage increase over recommended budgets.

    Valid values are 0 to 1500.

    budgetOnetimeLimit number

    One-time budget limit.

    If set, the campaign uses one budget for its full duration.

    Set either budgetOnetimeLimit or budgetMonthlyLimit, not both.

    The budget uses the employer account currency.

    Sponsored Jobs API parses, stores, and returns this value as an exact decimal fraction.

    budgetMonthlyLimit number

    Monthly budget limit.

    If set, the campaign uses a recurring monthly budget.

    For monthly budgets, the end date is optional.

    Set exactly one of budgetOnetimeLimit or budgetMonthlyLimit.

    The budget uses the employer account currency.

    Sponsored Jobs API parses, stores, and returns this value as an exact decimal fraction.

    budgetFirstMonthBehavior string

    Possible values: [startNowFullAmount, startNowProratedAmount, startNextMonthFullAmount]

    Default value: startNowFullAmount

    Use this field with budgetMonthlyLimit when startDate is not the first day of the month.

    It controls the first month budget.

    ValueFirst month budget
    startNowFullAmountFull monthly budget.
    startNowProratedAmountProrated based on days remaining in the month.
    startNextMonthFullAmountNo budget.

    Example: monthly budget 900 USD, start date June 11.

    ValueJune 11 to 30July 1 to 31
    startNowFullAmount900 USD900 USD
    startNowProratedAmount600 USD900 USD
    startNextMonthFullAmount0 USD900 USD
    startDate date

    Start date in ISO 8601 YYYY-MM-DD format.

    This is when the campaign starts sponsoring jobs.

    Default is the current date.

    The campaign starts at 12:00 AM US Central Time on that date.

    startDate must be today or later in US Central Time.

    If you omit startDate or set it to today, the campaign starts immediately.

    After the campaign is active and spending, you cannot update startDate.

    To pause a campaign, set status to PAUSED.

    fixedEndDate date

    Fixed end date for a one-time budget.

    On this date, the campaign must stop sponsoring jobs, even if budget remains.

    Use ISO 8601 YYYY-MM-DD format.

    For one-time budget campaigns (budgetOnetimeLimit), set either fixedEndDate or targetEndDate, not both.

    For monthly budget campaigns (budgetMonthlyLimit), fixedEndDate is optional.

    Without an end date, a monthly campaign runs until you pause or delete it.

    To stop at the start of a specific day, set fixedEndDate.

    The campaign stops at the start of that day in US Central Time.

    fixedEndDate must be at least one day after today in US Central Time, or one day after startDate if set.

    Example: if fixedEndDate is 2026-06-20, the campaign stops at 12:00 AM CT on June 20, 2026.

    targetEndDate date

    Target end date for sponsorship.

    The campaign may continue past this date if budget remains.

    Use ISO 8601 YYYY-MM-DD format.

    For one-time budget campaigns (budgetOnetimeLimit), set either fixedEndDate or targetEndDate, not both.

    For monthly budget campaigns (budgetMonthlyLimit), do not set targetEndDate.

    Monthly budget campaigns can use fixedEndDate or no end date.

    The target is the start of the specified day in US Central Time.

    targetEndDate must be at least one day after today in US Central Time, or one day after startDate if set.

    Example: if targetEndDate is 2026-06-20, the campaign targets 12:00 AM CT on June 20, 2026.

    fundingSource string

    Possible values: [Budget, Bonus Sponsored Job Credits]

    Default value: Budget

    Campaign funding source.

    Valid values are Budget (default) and Bonus Sponsored Job Credits.

    You cannot change the funding source after campaign creation.

    Annual Deals clients receive Bonus Sponsored Job Credits.

    They can use those credits for monthly or lifetime campaigns.

    objective

    object

    Hiring goals for the campaign.

    Setting this field makes the campaign an objective-based campaign.

    The value is a JSON object with:

    • objectiveType, which specifies the campaign objective

    • target, which specifies the goal metric for some objective types

    For example, to target 10 applications:

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

    You can add an objective to a campaign that does not already have one, and you can change the target value.

    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.

    You cannot update this field for average daily budget (ADB) campaigns ( STANDARD and PREMIUM).

    Available values:

    • BALANCE: Maximize total applications for your budget while balancing spend across jobs.

    • MAXIMUM: Maximize total applications for your budget without balancing clicks across jobs.

    • QUICK: Five-day campaign with a higher budget for faster results.

      You cannot create or update campaigns with this objective through Sponsored Jobs API.

      You can still retrieve reports for campaigns with this objective if they were created in Indeed for Employers.

    • TARGET_APPLICATIONS: Aim for the number of applications specified by target.

      When the target is reached, spend on those jobs is greatly reduced and shifted elsewhere.

    • TARGET_COST_PER_APPLICATION: Aim to keep the cost per application below the value specified by target.

    • SCHEDULED_INTERVIEWS: Send screened candidates directly to interview and aim for the number of interviews specified by target.

      This objective requires an active Indeed Hiring Platform subscription and should be used only if the customer is ready to create hiring events for the included jobs.

    Campaigns created outside your application might use new objective types that your application does not yet support.

    Add fallback logic to handle unexpected objectiveType values.

    any

    channels

    object[]

    Channel configuration list.

    This list does not include default channels.

    For example, to enable the TMN channel, set channels to:

    [
      {
        "channel": "TMN",
        "status": "CHANNEL_ENABLED"
      }
    ]

  • Array [

    • channel SpendingChannel

    Possible values: [TMN]

    Channel ID. Supported value:

    • TMN: Trusted Media Network.

    status ChannelStatus

    Possible values: [CHANNEL_ENABLED, CHANNEL_DISABLED]

    Channel spending status ID. Supported values:

    • CHANNEL_ENABLED: The channel can spend.

    • CHANNEL_DISABLED: The channel cannot spend.

  • ]

Responses​

Returns the new campaign ID in data.campaignId. The HTTP status is 201, not 200.

Schema

    meta

    object

    Response-related metadata.

    status int32

    HTTP status code of the response.

    errors

    object[]

    Errors that prevented the request from being processed successfully.

    If there are no errors, this 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.

  • ]

    • data

    object

    campaignId string
Loading...

Was this page helpful?