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 until you enable it, or temporarily stops sponsorship.
    • DELETED: Stops sponsorship and hides the campaign from the default view in the campaign management portal.
    trackingToken string

    Possible values: <= 255 characters

    Click-tracking token added to the job URL for sponsored clicks. Use it to identify clicks from Indeed and the campaign that sponsored them.

    jobsSourceId string

    Source ID string that overrides jobsSource. Identifies the job source this campaign sponsors jobs from. Specify the id of a job source returned in jobSourceList from GET /v1/account. If your employer account is not associated with any job sources yet, contact Indeed Customer Support.

    Each campaign supports only one jobsSourceId. If you have multiple job sources, create a separate campaign for each one.

    jobsSourceName string

    Source name (ATS partners only)

    jobsToInclude string

    Possible values: [ALL, QUERY]

    Required. ALL or QUERY.

    • ALL: Sponsors all jobs in the job source. The API ignores jobsQuery, jobsTitle, jobsCompany, jobsLocation, and jobsLocationRadius.

    • QUERY: Sponsors only jobs that match the specified criteria. If you specify more than one field, a job must match all of them.

      If you set jobsToInclude to QUERY and omit all criteria, the campaign currently sponsors all jobs in the job source. To avoid an error, specify at least one criterion, or set jobsToInclude to QUERY.

    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

    Jobs title in query. If set, the campaign sponsors only jobs with this title. Applies only when jobsToInclude is QUERY.

    jobsCompany string

    Jobs company in query. If set, the campaign sponsors only jobs from this hiring company. Applies only when jobsToInclude is QUERY.

    jobsLocation string

    Jobs location in 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 in query. 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.

    Required for average daily budget (ADB) campaigns:

    • Set budgetOnetimeLimit if the type is ONETIME.
    • Set budgetMonthlyLimit if the type is MONTHLY.

    Indeed optimizes spending toward the configured monthly or one-time budget.

    If the configured budget limit is high, Indeed might spend more than the recommended daily budget to meet the overall monthly or one-time budget target.

    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

    Boost 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.

    Newly added jobs, whether added manually or through query resolution, inherit the same percentage increase over their recommended budgets.

    Valid values: 0 to 1500.

    budgetOnetimeLimit number

    One-time budget limit. If set, the campaign uses one budget for its full duration. Specify either budgetOnetimeLimit or budgetMonthlyLimit, but not both.

    The budget uses the employer account's currency. Sponsored Jobs API parses, stores, and returns the value as an exact decimal fraction, not a floating-point number.

    budgetMonthlyLimit number

    Monthly budget limit. If set, the campaign uses a recurring monthly budget. The end date is optional for campaigns with a monthly budget.

    Specify exactly one of budgetOnetimeLimit or budgetMonthlyLimit.

    The budget uses the employer account's currency. Sponsored Jobs API parses, stores, and returns the value as an exact decimal fraction, not a floating-point number.

    budgetFirstMonthBehavior string

    Possible values: [startNowFullAmount, startNowProratedAmount, startNextMonthFullAmount]

    Default value: startNowFullAmount

    Used with budgetMonthlyLimit and a campaign startDate that is not the first day of the month, this field controls the first month's budget.

    ValueFirst month budget
    startNowFullAmount Full monthly budget.
    startNowProratedAmount Prorated based on the days remaining in the month.
    startNextMonthFullAmount No budget.

    This example uses a monthly budget of 900 USD, a start date of June 11, and each possible budgetFirstMonthBehavior value:

    ValueJune 11 to 30July 1 to 31
    startNowFullAmount 900 USD900 USD
    startNowProratedAmount 600 USD900 USD
    startNextMonthFullAmount 0 USD900 USD
    startDate date

    Start date for sponsoring jobs, in ISO 8601 YYYY-MM-DD format. Default: current date.

    The campaign starts at the beginning of that day in US Central Time (US/Central). The date must be the current date in CT or later.

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

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

    To pause a campaign temporarily, set status to PAUSED.

    fixedEndDate date

    Date when the campaign must stop sponsoring jobs, even if budget remains. Use ISO 8601 YYYY-MM-DD format.

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

    A campaign with a monthly recurring budget (budgetMonthlyLimit) can optionally have a fixedEndDate. Otherwise, the campaign continues until you manually pause or delete it. These are called evergreen campaigns.

    The campaign stops at the start of the specified day in US Central Time (CT, US/Central).

    The fixedEndDate must be at least one day after the current date in CT, or after the campaign startDate, if set.

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

    targetEndDate date

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

    A campaign with a one-time budget (budgetOnetimeLimit) must 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 must be 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 2026-06-20, the campaign targets June 20, 2021 at 0:00 AM CT.

    fundingSource string

    Possible values: [Budget, Bonus Sponsored Job Credits]

    Default value: Budget

    Funding source for the campaign. Valid values are Budget (default) or Bonus Sponsored Job Credits. You cannot change the funding source after you create the campaign.

    Annual Deals clients receive Bonus Sponsored Job Credits as part of their Annual Deals and can use them to create monthly or lifetime campaigns.

    objective

    object

    Hiring goals for the campaign. Setting this field makes the campaign an objective-based campaign.

    See Setting Up a Sponsored Job Campaign.

    This 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[]

    Channels do not include default channels.

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

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

  • Array [

    • channel SpendingChannelrequired

    Possible values: [TMN]

    Channel ID. Valid value is:

    • TMN : Trusted Media Network.
    status ChannelStatusrequired

    Possible values: [CHANNEL_ENABLED, CHANNEL_DISABLED]

    Channel spending status ID. Valid values are:

    • CHANNEL_ENABLED : Channel is enabled to spend
    • CHANNEL_DISABLED : Channel is disabled to 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[]

    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.

  • ]

    • data

    object

    campaignId string
Loading...

Was this page helpful?