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 scope | Access token type | | --- | --- | | employer.advertising.campaign | Access token that represents an employer. See Get access token that represents 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. Enables you to identify the campaign. 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. Enables you to determine that the click is from Indeed, and identify the campaign that sponsored the click.

    jobsSourceId string

    The job source that this campaign sponsors jobs from. Specify the id of one of the job sources returned in the jobSourceList field from GET /v1/account. Contact Indeed Customer Support if your employer account hasn't been associated with any job sources yet.

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

    jobsToInclude string

    Possible values: [ALL, QUERY]

    • ALL - Campaign sponsors all the jobs in the job source. The jobsQuery, jobsTitle, jobsCompany, jobsLocation, and jobsLocationRadius fields' values are ignored, and any existing values are cleared.
    • QUERY - Campaign sponsors a subset of jobs that match the criteria defined by jobsQuery, jobsTitle, jobsCompany, jobsLocation, and jobsLocationRadius fields. If more than one field is specified, 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 only sponsors 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 only sponsors jobs with this job title. Applies only if jobsToInclude is QUERY.

    jobsCompany string

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

    jobsLocation string

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

    jobsLocationRadius int32

    Default value: 25

    Specifies the 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.

    budgetOnetimeLimit number

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

    The budget is in the employer account's currency. Sponsored Jobs API parses, stores, and returns the value as an exact decimal fraction, and not 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 is in the employer account's currency. Sponsored Jobs API parses, stores, and returns the value as an exact decimal fraction, and not 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

    The date before when the campaign must stop sponsoring jobs, even if remaining unspent budget exists. 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

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

    Hiring goals that the campaign intends 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 applications, 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 jobs.
    • QUICK: Five day campaign with higher budget for faster results. Sponsored Jobs API does not 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 application could use newly added objective types that aren't yet supported by your application. Your application should have 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 SpendingChannel

    Possible values: [TMN]

    Channel ID. Valid value is:

    • TMN : Trusted Media Network.
    status ChannelStatus

    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?