Skip to main content

Create campaign

POST 
/v1/campaigns

Creates a sponsored jobs campaign.

Prerequisites

  • Before you can create a campaign, your employer account must be associated with a job source. Use the GET /v1/account endpoint to list job sources associated with your account. Contact Indeed Customer Support if your employer account hasn't been associated with any job sources yet.
  • Before a campaign starts sponsoring jobs, you must have set up valid billing information for your employer account.
OAuth scopeAccess token type
employer.advertising.campaign

Access token that represents an employer.

Request​

Body

required

Request body must be a JSON object that describes the campaign to create. Be sure to include the Content-Type: application/json header in the request.

You must always specify name, jobsSourceName, and jobsToInclude.

Selecting the jobs to sponsor

  • Sponsor all jobs in the job source: Set jobsToInclude to ALL. Don't specify jobsQuery, jobsTitle, jobsCompany, jobsLocation and jobsLocationRadius because they are ignored.
  • Sponsor a subset of jobs: Set jobsToInclude to QUERY. Specify at least one of jobsQuery, jobsTitle, jobsCompany, or jobsLocation.

Setting the campaign budget and duration

  • Create a campaign that stops on a specified date: Specify a budgetOnetimeLimit. Specify a fixedEndDate if you wish the campaign to stop sponsoring after the end date, even if it has unspent budget, or a targetEndDate to let the campaign continue sponsoring until it has spent its whole budget. (You can specify budgetMonthlyLimit instead if you prefer to set the budget in terms of a monthly amount and ensure that each month has equal budget, but you can only use fixedEndDate in that case.)
  • Create a campaign that sponsors jobs until manually stopped: Specify a budgetMonthlyLimit. Don't specify an end date.

Choosing when the campaign starts

  • Create a campaign that starts sponsoring immediately: This is the default if you don't specify a startDate or a status.
  • Create a campaign that starts on a specified future date: Specify a startDate.
  • Create a campaign that start when you manually enable it: Set status to PAUSED.

Optional features

  • Identify clicks sponsored by this campaign: Specify a trackingToken.
  • Optimize campaign behavior to achieve a specific hiring goal: Specify an objective. All campaigns created by Sponsored Jobs API are required to have an objective. If objectives are not provided by the employers at the time of campaign creation, Sponsored Jobs API selects the appropriate objective for the campaign.
  • Sponsor jobs on the Trusted Media Network (TMN): Specify channels. For more information, see What is the Trusted Media Network (TMN)?. After you create a campaign with an enabled or disabled channel, you cannot change the channel's status.

See the model definition for more details and example values for each field. See the How-to guides for campaign management for example requests.

    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.

    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.

    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.

    jobsToInclude string

    Possible values: [ALL, QUERY]

    Set to ALL to sponsor all the jobs in the job source, or QUERY to sponsor a subset of jobs.

    If ALL, this campaign sponsors all jobs in the jobs source. The values of jobsQuery, jobsTitle, jobsCompany, jobsLocation and jobsLocationRadius fields are ignored.

    If QUERY, this campaign sponsors the subset of jobs matching the criteria specified by jobsQuery, jobsTitle, jobsCompany, jobsLocation and jobsLocationRadius fields. If you specify more than one field, only jobs that match all the criteria are sponsored.

    Note: If jobsToInclude is QUERY but you omit all criteria, the campaign sponsors all jobs in the job source. In future API versions, this behavior becomes an error. Specify at least one criterion, or explicitly set jobsToInclude to ALL to sponsor all jobs.

    jobsQuery string

    If specified, the campaign sponsors only jobs containing these search terms. The query can contain complex boolean expressions. See Indexed jobs query format for details. Applies only if jobsToInclude is QUERY.

    jobsTitle string

    If specified, the campaign sponsors only jobs with this job title. Applies only if jobsToInclude is QUERY.

    jobsCompany string

    If specified, the campaign sponsors only jobs with this hiring company. Applies only if jobsToInclude is QUERY.

    jobsLocation string

    If specified, the campaign sponsors only jobs at or near this location. Applies only if jobsToInclude is QUERY.

    jobsLocationRadius int32

    Default value: 25

    Maximum distance between the job location and the location specified by jobsLocation. Valid value is 5, 10, 15, 25, 50, and 100. If the job is located in the United States or the United Kingdom, the unit is miles. Otherwise, the unit is kilometers.

    jobsSourceName string

    Source or company for this job, which must exactly match the sourcename node for the job in the XML job feed.

    budgetOnetimeLimit number

    If set, the campaign has a single budget for the whole duration of the campaign. You must always specify either budgetOnetimeLimit or budgetMonthlyLimit, but not both.

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

    budgetMonthlyLimit number

    If set, the campaign has a monthly recurring budget. The end date is optional for campaigns with a monthly recurring budget. Specify exactly one of budgetOnetimeLimit or budgetMonthlyLimit.

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

    budgetFirstMonthBehavior string

    Possible values: [startNowFullAmount, startNowProratedAmount, startNextMonthFullAmount]

    Default value: startNowFullAmount

    Along with budgetMonthlyLimit and a campaign start date other than the first day of the month, defines the behavior of the first month's budget. Value is:

    ValueFirst month budget
    startNowFullAmount Full monthly budget.
    startNowProratedAmountProportional to days in month after start date.
    startNextMonthFullAmount No budget.

    This table shows the budget for the first month and the subsequent month when the monthly budget is 900 USD, the start date is June 11, and budgetFirstMonthBehavior is set to one of these values:

    ValueJune 11 to 30July 1 to 31
    startNowFullAmount 900 USD900 USD
    startNowProratedAmount 600 USD900 USD
    startNextMonthFullAmount 0 USD900 USD
    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 must be 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) must 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 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 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) 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 2021-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

    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

    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 campaign ID of the new campaign as the data.campaignId field. Note that 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?