Provision Customer Hiring Contracts API

Article
03/29/2024

To manage jobs or campaigns like the P4P Job Campaign, there must be a customer contract created and associated with each child application. This "customer" contract is a child contract of the financial contract a partner signs to provision their Production dashboard with LinkedIn. The "financial (or parent)" contract here is the instance that is associated with the partner's parent Developer Application during self-provisioning activities by calling atsIntegrations API as in Update Customer Integrations.

This provisionedHiringContracts API is introduced to automate the provisioning of the customer/child contract under certain circumstances like managing campaigns of Partner P4P. Previously, all child contract provisioning had to be manually done by LinkedIn POC. With this API, one can self-serve creating & associating customer contracts almost in real time after creating a child Developer Application via Provisioning API. Please note that these customer contracts CANNOT be used to manage paid jobs such as Promoted Job Posting. All customer contracts created by this API share a total budget with the financial contract, so they are not meant to be managed independently.

API Overview

Use the /provisionedHiringContracts API to setup a customer contract. The API only supports the PARTNER_P4P type now which goes into the request body. There will be always a 1-to-1 mapping between a child Developer Application and a customer contract, and you will need to provide the child Developer Application information by providing the access token of the application. Upon success, one will get the contract ID in a response which he or she can use to manage the P4P Job Campaign.

API Authorization

All requests below require access tokens obtained via the OAuth2.0 Client Credentials flow. You MUST use the token from the child Developer Application you want to setup a contract for.

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.

Setup Contract

action=setup supports creation and provisioning of a new customer contract. Only 1 contract can be populated per call. Please use the following example to submit a request.

Setup Contract Sample Request

POST https://api.linkedin.com/rest/provisionedHiringContracts?action=setup
X-RestLi-Protocol-Version: 2.0.0
LinkedIn-Version: 202403
Authorization: Bearer {access_token}

Note

You must use the {access_token} from the child Developer Application you want to setup a contract and manage campaigns for the specific customer.
This is a versioned API. Linkedin-Version is required to provide to specify the right version to call.

Sample Request Body

{
   "contractType":"PARTNER_P4P"
}

Sample Response Body

{
     "key": "urn:li:developerApplication:12345",
     "contract": "urn:li:contract:67890",
     "contractType": "PARTNER_P4P"
 }

API Request Schema

Field	Description	Type	Required
contractType	The type of the contract that is to be provisioned for the customer. The available types are: `PARTNER_P4P`.	String	Yes

API Response Schema

Field	Description	Type	Required
key	Unique id (urn) per company.	String (`DeveloperApplicationUrn`)	Yes
contract	Unique id generated per key.	String (`ContractUrn`)	No
contractType	The type of the contract that is to be provisioned for the customer.	String	No

API Error Details

Response Code	HTTP Status	Message	Description	Resolution
1000	400	The developer application is not found.	The token used to send the request is invalid.	Please check the developer application token used in the API.
1001	409	{key} already has a contract: {contractUrn}.	The customer dev app provided already has a contract assigned to it.	No action needed.
1002	400	The contract type is not supported.	The contract type used in the request body is invalid.	Please ensure a valid contractType is used.
2000	500	Internal Server Error.	There was some server error in setting up the customer.	Please reach out to LinkedIn support with details such as `X-LI-UUID` and sample request & response.

Partager via