Get campaign budget and duration

GET 
/v1/campaigns/:campaignId/budget

Gets a campaign's budget and duration.

Request the employer.advertising.campaign.read OAuth scope to get an access token that represents an employer. See Get access token that represents employer.

OAuth scope	Access token type
employer.advertising.campaign.read	Access token that represents an employer. See Get access token that represents employer.

Request

Path Parameters

campaignId stringrequired

Campaign ID.

Responses

200

Success

application/json

Schema

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

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.

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.

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 format of YYYY-MM-DD.

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 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 may continue sponsoring past the given date if it hasn't spent its whole budget yet. Follows the ISO 8601 format of YYYY-MM-DD.

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.

Example (from schema)

{
  "meta": {
    "status": 200,
    "errors": [
      {
        "type": "RESOURCE_NOT_FOUND",
        "description": "Couldn't locate the requested resource"
      }
    ],
    "rootLocation": "https://apis.indeed.com/ads",
    "perPage": 25,
    "links": [
      {
        "rel": "next",
        "href": "/v1/campaigns/3141592653589793"
      }
    ]
  },
  "data": {
    "budgetOnetimeLimit": 10000,
    "budgetMonthlyLimit": 10000,
    "dailyAvgBudgetPerJob": 2000,
    "startDate": "2021-01-15",
    "fixedEndDate": "2021-06-20",
    "targetEndDate": "2021-05-01"
  }
}

One-time budget

{
  "meta": {
    "status": 200,
    "errors": null,
    "rootLocation": "https://apis.indeed.com/ads",
    "perPage": null,
    "links": [
      {
        "rel": "up",
        "href": "/v1/campaigns"
      },
      {
        "rel": "Campaign Info",
        "href": "/v1/campaigns/cda7fa7645b613d5"
      }
    ]
  },
  "data": {
    "budgetOnetimeLimit": 10000,
    "startDate": "2022-05-20",
    "targetEndDate": "2024-01-20"
  }
}

Monthly recurring budget

{
  "meta": {
    "status": 200,
    "errors": null,
    "rootLocation": "https://apis.indeed.com/ads",
    "perPage": null,
    "links": [
      {
        "rel": "up",
        "href": "/v1/campaigns"
      },
      {
        "rel": "Campaign Info",
        "href": "/v1/campaigns/cda7fa7645b613d5"
      }
    ]
  },
  "data": {
    "budgetMonthlyLimit": 6000,
    "startDate": "2022-03-13"
  }
}

Daily Average Budget Per Job

{
  "meta": {
    "status": 200,
    "errors": null,
    "rootLocation": "https://apis.indeed.com/ads",
    "perPage": null,
    "links": [
      {
        "rel": "up",
        "href": "/v1/campaigns"
      },
      {
        "rel": "Campaign Info",
        "href": "/v1/campaigns/cda7fa7645b613d5"
      }
    ]
  },
  "data": {
    "dailyAvgBudgetPerJob": 500,
    "startDate": "2022-03-13",
    "targetEndDate": "2024-01-20"
  }
}

401

Request did not include a valid access token:

• The Authorization header is missing or malformed. Include the access token using the Bearer scheme — for example, Authorization: Bearer XYZ.

• The access token is malformed. When building requests manually, check that you copied the token without missing or extra characters at the start or end.

• The access token has expired. Tokens expire after one hour (3,600 seconds). Get a new token using your client credentials (2-legged OAuth) or a refresh token (3-legged OAuth).

application/json

Schema

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

Example (from schema)

{
  "meta": {
    "status": 200,
    "errors": [
      {
        "type": "RESOURCE_NOT_FOUND",
        "description": "Couldn't locate the requested resource"
      }
    ],
    "rootLocation": "https://apis.indeed.com/ads",
    "perPage": 25,
    "links": [
      {
        "rel": "next",
        "href": "/v1/campaigns/3141592653589793"
      }
    ]
  },
  "data": null
}

Example

{
  "meta": {
    "status": 401,
    "errors": [
      {
        "type": "INVALID_TOKEN",
        "description": "Invalid OAuth access token."
      }
    ],
    "rootLocation": "https://apis.indeed.com/ads",
    "perPage": null,
    "links": null
  },
  "data": null
}

403

Valid access token that cannot be used with this API. Inspect the error returned in the meta.errors for details.

Error type	Meaning and common causes
INSUFFICIENT_SCOPE	The access token does not have the OAuth v2 token scope required for this API endpoint. For common causes, see FAQ and troubleshooting.
NOT_EMPLOYER_ACCESS_TOKEN	This endpoint requires an access token that represents an employer. See Get access token that represents employer. That is, you must specify the employer parameter when requesting the access token. You need to do this for the majority of the Sponsored Jobs API endpoints.
LEGACY_ACCESS_TOKEN_NOT_ALLOWED	Sponsored Jobs API no longer supports access tokens that you get through legacy OAuth endpoints. For updated endpoints, see Integrate with Indeed and call APIs

application/json

Schema

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

Example (from schema)

{
  "meta": {
    "status": 200,
    "errors": [
      {
        "type": "RESOURCE_NOT_FOUND",
        "description": "Couldn't locate the requested resource"
      }
    ],
    "rootLocation": "https://apis.indeed.com/ads",
    "perPage": 25,
    "links": [
      {
        "rel": "next",
        "href": "/v1/campaigns/3141592653589793"
      }
    ]
  },
  "data": null
}

Example

{
  "meta": {
    "status": 403,
    "errors": [
      {
        "type": "INSUFFICIENT_SCOPE",
        "description": "Access token does not have permission to access this API."
      }
    ],
    "rootLocation": "https://apis.indeed.com/ads",
    "perPage": null,
    "links": null
  },
  "data": null
}

404

Requested campaign either does not exist or belongs to another employer. Be sure to use an access token that represents the employer that owns the requested campaign. See Get access token that represents employer.

application/json

Schema

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

Example (from schema)

{
  "meta": {
    "status": 200,
    "errors": [
      {
        "type": "RESOURCE_NOT_FOUND",
        "description": "Couldn't locate the requested resource"
      }
    ],
    "rootLocation": "https://apis.indeed.com/ads",
    "perPage": 25,
    "links": [
      {
        "rel": "next",
        "href": "/v1/campaigns/3141592653589793"
      }
    ]
  },
  "data": null
}

Example

{
  "meta": {
    "status": 404,
    "errors": [
      {
        "type": "RESOURCE_NOT_FOUND",
        "description": "Couldn't locate the requested resource."
      }
    ],
    "rootLocation": "https://apis.indeed.com/ads",
    "perPage": null,
    "links": {
      "rel": "up",
      "href": "/v1/campaigns"
    }
  },
  "data": null
}

500

Unexpected error occurred. The problem is sometimes temporary and the exact same request may succeed after retrying.

If retrying the request does not help, a problem with parsing the request might have occurred. Make sure that all the required parameters are present and that all parameters are correctly formatted.

If you use an access token obtained with client credentials grant type (2-legged OAuth) with the legacy Sponsored Jobs API endpoint, the INTERNAL_SERVER_ERROR error occurs. Be sure to use the latest base URL (https://apis.indeed.com/ads).

application/json

Schema

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

Example (from schema)

{
  "meta": {
    "status": 200,
    "errors": [
      {
        "type": "RESOURCE_NOT_FOUND",
        "description": "Couldn't locate the requested resource"
      }
    ],
    "rootLocation": "https://apis.indeed.com/ads",
    "perPage": 25,
    "links": [
      {
        "rel": "next",
        "href": "/v1/campaigns/3141592653589793"
      }
    ]
  },
  "data": null
}

Example

{
  "meta": {
    "status": 500,
    "errors": [
      {
        "type": "INTERNAL_SERVER_ERROR",
        "description": "Failed to process the request."
      }
    ],
    "rootLocation": "https://apis.indeed.com/ads",
    "perPage": null,
    "links": null
  },
  "data": null
}

Loading...

 

Was this page helpful?