Provision Customer Hiring Contracts API

2025-05-12

To manage jobs, 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 P4P jobs. 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 the same financial information with the financial contract, so they are not meant to be managed independently.

API Overview

Use the /provisionedHiringContracts API to set up a customer or child contract. The API takes a partner contract ID in the request body. If a partner contract ID is not provided and the partner only has one contract, that contract will be used by default. Otherwise, the request will fail. There will always be a 1-to-1 mapping between a pair of Child Developer Application & partner contract (via parent application) and a customer contract. You must provide the Child Developer Application information by providing the 2L OAuth access token generated from the child to invoke /provisionedHiringContracts?action=setup. Upon success, you will get the contract ID in a response which can be recorded. After that, you can start using the customer contract ID or the original partner contract ID (along with the corresponding Child developer application token) to manage jobs.

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: 202503
Authorization: Bearer {access_token}

Note

You must use the {access_token} from the Child Developer Application you want to setup a contract and manage jobs 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

{
  "partnerContractId": 123456
}

Sample Response Body

{
  "value": {
      "key": "urn:li:developerApplication:012345",
      "contract": "urn:li:contract:67890"
   }
 }

API Request Schema

Field	Description	Type	Required
partnerContractId	The ID of the financial (parent) contract to which the job product purchased by the partner was provisioned.	Long	Yes

API Response Schema

Field	Description	Type	Required
key	Unique application ID (urn) per client or company.	String (`DeveloperApplicationUrn`)	Yes
contract	Clients can use either this ID or the `partnerContractId` to manage jobs.	String (`ContractUrn`)	No

API Error Details

Response Code	HTTP Status	Message	Description	Resolution
(No Code Returns)	400	invalid_client_id.	The passed in client_id is invalid {client ID}.	Please retry.
100	403	ACCESS_DENIED.	Not enough permissions to access: provisionedHiringContracts.ACTION-setup.{version number}.	Please retry.
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}.	Please ensure a partner contract id is provided when the partner has multiple contracts.
1003	400	`partnerContractId` must be provided since the partner has multiple partner contracts.	For partners that have multiple contracts, a partner contract is must be provided when interacting with this API.	Please ensure a valid contractType is used.
1004	400	The partner contract id is invalid.	The partner contract id used in the request body is not valid.	Please ensure a valid partner contract id 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