Pay For Performance (P4P) Job Campaign API

Article
09/09/2024

LinkedIn's Pay For Performance (P4P) Campaign API allows partners to create and manage a campaign that categorizes and groups their customers' P4P jobs under the same goal and contract.

Note

If you are an individual job promotion partner, such as JD or ATS, you will NOT need this Campaign API to manage your jobs.

API Overview

Use the /jobCampaigns API to create, pause, resume, update and close P4P campaigns. This API mainly targets job marketing companies such as a Recruitment Advertising Agency (RAA). The campaign can have a multiple jobs under each common goal while one campaign is specific to one contract that is dedicated to one customer. On the other direction, each customer will have one P4P contract and a contract can contain a multiple campaigns based on partners' convenience.

API Authorization

All requests below require access tokens obtained via the OAuth2.0 Client Credentials flow. You MUST use the token from the same Developer Application (or clientId) as you used to create the job.

Important

We strongly recommend to use same access token for all concurrent and consecutive calls. An access token has a lifespan of 30 mins. Only on expiry of the existing token should a new token should be generated.

Create Campaign

CREATE supports creation of new LinkedIn campaigns. A campaign will be associated with a specific contract and will execute based on startTime and endTime. Please use the following example to submit a task to create (asynchronous), pause, resume, update and close a campaign.

Create Campaign Sample Request

POST https://api.linkedin.com/rest/jobCampaigns
X-RestLi-Protocol-Version: 2.0.0
LinkedIn-Version: 202311
Authorization: Bearer {access_token}

Note

You must use the {access_token} from the same Developer Application (e.g. matching partnerCustomerId) that you sent the jobs with.
This is a versioned API. Linkedin-Version is required to provide to specify the right version to call.
Ensure that requests do not include duplicate updates to the same campaignId.
Please check Campaign API Schema for required fields.
You can create up to 10,000 Campaigns per customer.

Sample Request Body

{
  "partnerJobCampaignName": "Test Campaign", 
  "partnerJobCampaignId": "abcd1234",
  "startAt": 1701210598000,
  "endAt": 1735597798000,
  "optimizationParameters": {
    "chargeEvent": "VIEW",
    "maxAvgCost": "5"
  },
  "optimizationGoal": "MAX_APPLY_CLICK",
  "budget": "2000",
  "currencyCode": "USD",
  "operation": "CREATE"
}

Sample Response Body

A successful request returns a 201 response code.

API Error Details

Response Code	HTTP Status	Error Message	Description	Resolution
AB1000	422	Please add a create campaign payload.	The campaign payload is empty.	Please add a payload with the campaign entity to create it.
AB1001	422	ERROR: Required field is not found and has no default value:{}.	A required field is not found in the campaign entity.	Refer to the schema documentation and ensure all the required fields are present in the request body.
AB1002	400	Campaign name is too long.	The `partnerJobCampaignName` field is too long.	The name can have a maximum of 255 characters.
AB1003	400	PartnerJobCampaignId is invalid.	The `partnerJobCampaignId` field is invalid.	Refer to the schema documentation and provide a valid id.
AB1004	400	Start time is invalid.	The `startAt` time is invalid.	The `startAt` time can be current or in the future.
AB1005	400	End time is invalid.	The `endAt` time is invalid.	The `endAt` time should be atleast one day after the `startAt` time and should be in the future.
AB1006	400	Budget amount is invalid.	The `budget.amount` is invalid.	Ensure that the correct budget amount is provided.
AB1007	400	Budget currency code is invalid.	The `currencyCode` is invalid.	Ensure that the currencyCode provided is in the correct format.
AB1008	400	Currency code of the max average cost is invalid.	The `currencyCode` of the `maxAvgCost` field in optimization parameters is invalid.	Ensure that the currencyCode provided is in the correct format.
AB1009	400	Max average cost amount is invalid.	The `maxAvgCost` is invalid.	Ensure that the correct maxAvgCost amount is provided.
AB1010	400	Charge event is invalid.	The `chargeEvent` is invalid.	Ensure that the correct chargeEvent value is provided.
AB1011	400	Optimization goal is invalid.	The `optimizationGoal` is invalid.	Ensure that the correct optimizationGoal value is provided.
AB1012	400	PartnerJobCampaignId is too long.	The partnerJobCampaignId field contains too many characters.	The id can have a maximum of 255 characters.

Get Campaign

GET retrieves the campaign information based on the campaignId provided. You MUST use the Developer Application (or clientId) that was used to create a campaign to get the campaign.

Get Campaign Sample Request

GET https://api.linkedin.com/rest/jobCampaigns/<partnerJobCampaignId>
X-RestLi-Protocol-Version: 2.0.0
LinkedIn-Version: 202311
Authorization: Bearer {access_token}

Sample Response Body

A successful request returns a 200 OK response code.

{
  "partnerJobCampaignName": "Test Campaign", 
  "partnerJobCampaignId": "abcd1234",
  "startAt": 1701210598000,
  "endAt": 1735597798000,
  "optimizationParameters": {
    "chargeEvent": "VIEW",
    "maxAvgCost": "5"
  },
  "optimizationGoal": "MAX_APPLY_CLICK",
  "budget": "2000",
  "currencyCode": "USD",
  "state" : "ACTIVE"
}

API Error Details

Please see Campaign API Error Details below for a list of possible API errors.

Update Campaign

UPDATE allows you to update available field values. One can update partnerJobCampaignName, startAt (only under certain condition), endAt, budget, optimizationGoal and optimizationParameters. Please include all the parameters which are required by the Campaign API Schema in the request body. You MUST use the Developer Application (or clientId) to update a campaign that was used to create the campaign.

Note

If a field is NOT present, its value will be DELETED.
Changing the optimizationGoal or optimizationParameters might affect the effectiveness of the optimization.
partnerJobCampaignId and currencyCode cannot be changed.
If the campaign is ACTIVE, then startAt cannot be changed.
endAt cannot be in the past or before startAt.

Update Campaign Sample Request

POST https://api.linkedin.com/rest/jobCampaigns
X-RestLi-Protocol-Version: 2.0.0
LinkedIn-Version: 202311
Content-Type: application/json
Authorization: Bearer {access_token}

Sample Request Body

{
  "partnerJobCampaignId": "abcd1234",
  "partnerJobCampaignName": "testUpdate",
  "startAt": 1701210598000,
  "endAt": 1735597798000,
  "budget": "2000.00",
  "currencyCode": "USD",
  "optimizationGoal": "MAX_APPLY_CLICK",
  "optimizationParameters": {
    "chargeEvent": "VIEW",
    "maxAvgCost": "20.00"
  },
  "operation" : "UPDATE"
}

Sample Response

A successful request returns a 200 OK response code.

API Error Details

Response Code	HTTP Status	Error Message	Description	Resolution
AC1000	422	Please check the upload payload.	The payload for update is invalid.	Refer to the schema documentation and ensure all the required fields are present in the request body.
AC1001	400	ERROR: partnerJobCampaignId cannot be changed.	The `partnerJobCampaignId` field cannot be changed once set.	Please correct the id.
AC1002	400	ERROR: partnerId cannot be changed.	The `partnerId` used to create the token cannot be changed.	Please correct the partner id.
AC1003	400	ERROR: customer contract cannot be changed.	The customer contract used to create the token cannot be changed.	Please correct the customer contract.
AC1004	400	ERROR: startTime cannot be changed.	The start time of an `ACTIVE` campaign cannot be changed.	Please correct the startAt time.
AC1005	400	ERROR: startTime is invalid.	The new `startAt` time given is invalid.	The startAt time can be current or in the future.
AC1006	400	ERROR: endTime is invalid.	The new `endAt` time given is invalid.	The endAt time should be atleast one day after the startAt time and should be in the future.
AC1007	400	ERROR: budget amount is invalid.	The new `budget.amount` is invalid.	Ensure that the correct budget amount is provided.
AC1008	400	ERROR: budget currency code is invalid.	The new `currencyCode` is invalid.	Ensure that the currencyCode provided is in the correct format.
AC1009	400	ERROR: campaign name is too long.	The new `partnerJobCampaignName` field is too long.	The name can have a maximum of 255 characters.
AC1010	400	ERROR: max average cost amount is invalid.	The new `maxAvgCost` is invalid.	Ensure that the correct maxAvgCost amount is provided.
AC1011	400	ERROR: currency code of the max average cost is invalid.	The `currencyCode` of the `maxAvgCost` field in optimization parameters is invalid.	Ensure that the currencyCode provided is in the correct format.
AC1014	400	ERROR: Budget cannot be set below the current campaign spend.	The new budget is less than the amount spent so far for the campaign.	Ensure that a valid budget amount is provided.

Stop Campaign

STOP allows you to stop a scheduled or active campaign. You should include the partnerJobCampaignId of the campaign that needs to be stopped in the URL.

Stop Campaign Sample Request

POST https://api.linkedin.com/rest/jobCampaigns/<partnerJobCampaignId>?action=stop
X-RestLi-Protocol-Version: 2.0.0
LinkedIn-Version: 202311
Authorization: Bearer {access_token}

Sample Response

A successful request returns a 200 OK response code.

API Error Details

Response Code	HTTP Status	Error Message	Description	Resolution
AD1000	404	Campaign does not exist.	The given campaign does not exist.	Please check the partnerJobCampaignId.
AD1001	400	Campaign is already stopped.	The campaign is already in a `STOPPED` state.	No action necessary.

Resume Campaign

This action is used to resume a stopped campaign. One can provide new optional startAt and endAt times for resuming the campaign. The campaign will be scheduled or active, depending on the startAt time. You should include the partnerJobCampaignId of the campaign that needs to be resumed in the URL.

Resume Campaign Sample Request

POST https://api.linkedin.com/rest/jobCampaigns/<partnerJobCampaignId>?action=resume
X-RestLi-Protocol-Version: 2.0.0
LinkedIn-Version: 202311
Content-Type: application/json
Authorization: Bearer {access_token}

Note

startAt and endAt are optional to resume.

Sample Request Body

{
  "startAt": 1701210598000,
  "endAt": 1735597798000
}

Sample Response

A successful request returns a 200 OK response code.

API Error Details

Response Code	HTTP Status	Error Message	Description	Resolution
AE1000	404	Campaign does not exist.	The given campaign does not exist.	Please check the partnerJobCampaignId.
AE1001	400	Campaign can only be resumed if it is in stopped state.	The given campaign is not stopped.	No action necessary.
AE1002	400	Start time is invalid.	The new `startAt` time given is invalid.	The startAt time can be current or in the future.
AE1003	400	End time is invalid.	The new `endAt` time given is invalid.	The endAt time should be atleast one day after the startAt time and should be in the future.

Campaign API Schema

Field	Description	Type	Required
partnerJobCampaignName	The name of the campaign.	String	Yes
partnerJobCampaignId	Unique id per campaign from the partner. Maximum of 255 characters.	String	Yes
startAt	Represents the time when the campaign should start. The time is epoch timestamp in milliseconds (UTC) and should not be in the past.	Long	Yes
endAt	Represents the time when the campaign should be stopped. The time is epoch timestamp in milliseconds (UTC) and should be after the `startAt` time. If set, the campaign will be stopped at the `endAt` time. If not set, the campaign will keep running.	Long	Yes
optimizationParameters	The basic parameters of the campaign used in achieving the campaign goal. Any updates to this may have a delayed and/or limited effect if the campaign has already started.	JobCampaignOptimizationParameters	Yes
optimizationGoal	The optimization goal for the campaign to deliver. `MAX_APPLY_CLICK` – LinkedIn will optimize to maximize the delivery of apply click events to the job apply URL with the consideration that LinkedIn will not try to push budget towards jobs that are easier to get apply clicks. Default value is `MAX_APPLY_CLICK`.	String	No
budget	The maximum amount to be spent for promoting jobs for the campaign in its lifetime.	String	Yes
currencyCode	ISO currency code of the amount.	String	Yes
state	The current status of the campaign (e.g. `SCHEDULED`, `ACTIVE` & `STOPPED`). This is a read-only field.	String	No
operation	Represents the operation on the job campaign. Available options are: `CREATE` and `UPDATE`. For `Write`-type operations, such as `CREATE`, you must provide the valid option.	String	No

Note

Allowed characters are alphanumeric, dash, and underscores. Please NEVER use commas, semicolons, or pipes ("|").

JobCampaignOptimizationParameters Field Schema

Field	Description	Type	Required
chargeEvent	The outcome event that triggers charges. Default value is `VIEW`.	String	Yes
maxAvgCost	The maximum average cost for the delivery event for the campaign's optimization goal. If not provided, there is no constraint. The currency is the same as that for the campaign. NOTE that this constraint cannot be achieved strictly exactly. It is on a best effort basis.	String	No

Campaign API Error Details

Generic Errors

Response Code	HTTP Status	Error Message	Description	Resolution
AA1000	403	Caller is not authorized to access the campaign.	The application does not have enough permissions to use `/jobCampaigns` API.	Ensure that you are using the correct Developer Application Id or child Developer Application Id to create a token.
AA1001	404	Unable to find associated partner campaign {id}.	The campaign which is being accessed does not exist.	Ensure that the correct partnerJobCampaignId is provided.
AA1002	404	Resource {name} does not exist.	API URL format is incorrect.	Please verify the URL format from documentation and sample code.
AA1003	500	Internal Server Error.	There was some issue in processing the request.	Ensure that the request payload and headers are correct and try again.
AA1004	504	Gateway Timeout.	Invalid API request.	Please recheck all headers and API payload.
AA1005	400	Invalid operation: {}.	The operation used in the payload is invalid.	Please check the payload.
AA1006	422	Invalid payload.	The payload is invalid.	Please check the payload.
AA1007	403	Caller is not authorized to access the job campaigns API, unable to find a valid Developer Application.	The Developer Application could not be processed.	Please check the access token.
AA1008	403	Caller is not authorized to access the job campaigns API, unable to find a valid customer contract.	The customer contract could not be processed.	Please check the access token.
AA1009	403	Caller is not authorized to access the job campaigns API, unable to find a valid partner ATS.	The partner information could not be processed.	Please check the access token.

Field Not Found Errors

Response Code	HTTP Status	Error Message	Description	Resolution
AF1000	400	Error: partnerJobCampaignId not found in the payload.	The `partnerJobCampaignId` field is not present.	Please include the partnerJobCampaignId in the payload.
AF1001	400	Error: partner not resolved from the access token.	The partner cannot be resolved from the access token.	Please include the partner in the token.
AF1002	400	Error: customer contract not resolved from the access token.	The customer contract cannot be resolved from the access token.	Please include the customer contract in the token.
AF1003	400	Error: startAt not found in the payload.	The `startAt` field is not present.	Please include the startAt in the payload.
AF1004	400	Error: endAt not found in the payload.	The `endAt` field is not present.	Please include the endAt in the payload.
AF1005	400	Error: budget amount not found in the payload.	The `budget.amount` field is not present.	Please include the budget amount in the payload.
AF1006	400	Error: budget currency code not found in the payload.	The `budget.currencyCode` field is not present.	Please include the budget currency code in the payload.
AF1007	400	Error: campaign name not found in the payload.	The campaign `name` field is not present.	Please include the campaign name in the payload.
AF1008	400	Error: optimization params not found in the payload.	The optimization params field is not present.	Please include the optimization params in the payload.
AF1009	400	Error: charge event not found in the payload.	The charge event field is not present.	Please include the charge event in the payload.

Field Cannot Be Deleted Errors

Response Code	HTTP Status	Error Message	Description	Resolution
AG1000	400	Error: partnerJobCampaignId cannot be deleted.	The `partnerJobCampaignId` field cannot be deleted.	Please include the partnerJobCampaignId in the payload.
AG1001	400	Error: partner cannot be deleted.	The partner cannot be deleted.	Please include the partner in the token.
AG1002	400	Error: customer contract cannot be deleted.	The customer contract cannot be deleted.	Please include the customer contract in the token.
AG1003	400	Error: campaign name cannot be deleted.	The campaign `name` field cannot be deleted.	Please include the campaign name in the payload.
AG1004	400	Error: startAt cannot be deleted.	The `startAt` field cannot be deleted.	Please include the startAt in the payload.
AG1005	400	Error: endAt cannot be deleted.	The `endAt` field cannot be deleted.	Please include the endAt in the payload.
AG1006	400	Error: budget amount cannot be deleted.	The `budget.amount` field cannot be deleted.	Please include the budget amount in the payload.
AG1007	400	Error: budget currency code cannot be deleted.	The `budget.currencyCode` field cannot be deleted.	Please include the budget currency code in the payload.
AG1008	400	Error: optimization params cannot be deleted.	The optimization params field cannot be deleted.	Please include the optimization params in the payload.
AG1009	400	Error: charge event cannot be deleted.	The charge event field cannot be deleted.	Please include the charge event in the payload.

Partager via

Pay For Performance (P4P) Job Campaign API

API Overview

API Authorization

Create Campaign

Create Campaign Sample Request

Sample Request Body

Sample Response Body

API Error Details

Get Campaign

Get Campaign Sample Request

Sample Response Body

API Error Details

Update Campaign

Update Campaign Sample Request

Sample Request Body

Sample Response

API Error Details

Stop Campaign

Stop Campaign Sample Request

Sample Response

API Error Details

Resume Campaign

Resume Campaign Sample Request

Sample Request Body

Sample Response

API Error Details

Campaign API Schema

JobCampaignOptimizationParameters Field Schema

Campaign API Error Details

Generic Errors

Field Not Found Errors

Field Cannot Be Deleted Errors

Commentaires

Ressources supplémentaires