Jobs Ads API

  • Article

Warning

Deprecation Notice
The Marketing version 202304 (Marketing April 2023) and below has been sunset and the unversioned APIs are going to be sunset soon. We recommend that you migrate to the versioned APIs as well as migrate to the new Content and Community Management APIs to avoid disruptions. See the Migration page for more details. If you haven’t yet migrated and have questions, submit a request on the LinkedIn Developer Support Portal.

Linkedin is introducing its next generation of APIs for the creation and management of Dynamic Job Ads.

Permissions

Permission Possible Values
rw_ads Manage and read an authenticated member's Ad Accounts. In addition, authenticated member must have READ access for a Company Page. Have one of the following Ad Account roles:
  • ACCOUNT_BILLING_ADMIN
  • ACCOUNT_MANAGER
  • CAMPAIGN_MANAGER
  • CREATIVE_MANAGER
    		•
    r_ads Read an authenticated member's Ad Account. Restricted to Ad Accounts in which the authenticated member has one of the following Ad Account roles.
  • ACCOUNT_BILLING_ADMIN
  • ACCOUNT_MANAGER
  • CAMPAIGN_MANAGER
  • CREATIVE_MANAGER
  • VIEWER
    		•

    Workflow

    1. Upload an image asset. The Image API replaces the Assets API, with simplified and consistent schema. Refer to Images API for more information.

    2. Create a Dynamic Ads Campaign. See Dynamic Ad Campaigns.

    3. Design a Creative. The new Creatives API replaces the adCreativesV2 API, and features dynamic job ad format fields for easier creative design and development. For more details refer to the schema section below.

    Schema

    Field Type Description Required
    buttonLabel Either a preApproved string or a custom string The button label at the bottom of the ad when there are at least three jobs for the member. Not used for mobile job ads. It can follow either of the following formats:
    1. {"preApproved": "{label}"} Pre-approved and localized follower description text not subject to review process. Standard values:
      • SEE_MORE_JOBS - See More Jobs
      • VIEW_MORE - View More
      • CAREERS_AT_COMPANY - Careers at {companyName}
    2. {"custom": "{label}"} Custom buttonLabel text subject to Ads review process.
    		 Yes
    showMemberProfilePhoto boolean Boolean value that helps decide whether to display profile photo of member in the job ad or not. Defaults to true. No
    headline Either a preApproved string or a custom string The headline of the ad. It is the main message seen by your target audience. Not used for mobile job ads. It can follow either of the following formats:
    1. {"preApproved": "{label}"} Pre-approved and localized jobs headline text not subject to Ads review process. Standard values:
      • MEMBER_READY_FOR_YOUR_DREAM_JOB - {memberName}, ready for your dream job?
      • MEMBER_PICTURE_YOURSELF_AT_COMPANY - {memberName}, picture yourself at {companyName}
      • MEMBER_YOU_MAY_BE_INTERESTED_IN_THIS_INTERNAL_ROLE - {memberName}, you may be interested in this internal role
      • MEMBER_YOU_MAY_BE_INTERESTED_IN_THESE_INTERNAL_ROLES - {memberName}, you may be interested in these internal role(s)
      • MEMBER_YOU_MAY_BE_INTERESTED_IN_THESE_INTERNAL_ROLES_PLURAL - {memberName}, you may be interested in these internal roles
      • MEMBER_EXPLORE_INTERNAL_ROLES_AT_COMPANY_THAT_MATCH_YOUR_SKILLS - {memberName}, explore internal roles at {companyName} that match your skills
      • MEMBER_EXPLORE_JOBS_AT_COMPANY_THAT_MATCH_YOUR_SKILLS - {memberName}, explore jobs at {companyName} that match your skills
      • MEMBER_NEED_A_NEW_CHALLENGE_WE_CAN_HELP - {memberName}, need a new challenge? We can help!
      • MEMBER_WORK_WITH_US_AT_COMPANY - {memberName}, work with us at {companyName}
    2. {"custom": "{label}"} Custom headline text subject to Ads review process.
    		 Yes
    logo ImageUrn Company logo. This may differ from the logo on the official company page. If not present on create, the logo from company page is used.This is optional on creates, but will always be present on reads. Setting it to null on update would default to the logo from company page. No
    organizationName string Company name to use in the ad. This may differ from the name on the official company page. If not present on create, the company name from company page is used. This is optional on creates, but will always be present on reads. Setting it to null on update would default to the name from company page. No
    Attribute Possible Values
    Campaign Type DYNAMIC
    Campaign Format JOBS
    Creative Type JOBS_V2
    Objective Type JOB_APPLICANT

    Create a Dynamic Job Ad Creative

    POST https://api.linkedin.com/rest/creatives

    {
    "content": {
        "jobs": {
            "organizationName": "Test Company Name",
            "logo": "urn:li:image:C4E22AQExxAnf-VY49w",
            "headline": {
                "preApproved": "MEMBER_NEED_A_NEW_CHALLENGE_WE_CAN_HELP"
            },
            "buttonLabel": {
                "preApproved": "CAREERS_AT_COMPANY"
            },
            "showMemberProfilePhoto": true
        }
    },
    "campaign": "urn:li:sponsoredCampaign:190357284",
    "intendedStatus": "ACTIVE"
}

    A successful response returns a 201 Created HTTP status code and the ID in the x-linkedin-id response header. For example, urn:li:sponsoredCreative:120491345

    Get a Dynamic Job Ad Creative

    GET https://api.linkedin.com/rest/creatives/{sponsoredCreative-urn}

    Sample Response

    {
    "servingHoldReasons": [
        "UNDER_REVIEW",
        "CAMPAIGN_STOPPED"
    ],
    "lastModifiedAt": 1643767858000,
    "lastModifiedBy": "urn:li:person:B1U4S2MZ-C",
    "content": {
        "jobs": {
            "logo": "urn:li:image:C4E22AQExxAnf-VY49w",
            "showMemberProfilePhoto": true,
            "organizationName": "Test Company Name",
            "headline": {
                "preApproved": "MEMBER_NEED_A_NEW_CHALLENGE_WE_CAN_HELP"
            },
            "buttonLabel": {
                "preApproved": "CAREERS_AT_COMPANY"
            }
        }
    },
    "createdAt": 1643767858000,
    "isTest": false,
    "createdBy": "urn:li:person:B1U4S2MZ-C",
    "review": {
        "status": "PENDING"
    },
    "isServing": false,
    "campaign": "urn:li:sponsoredCampaign:190357284",
    "id": "urn:li:sponsoredCreative:160701894",
    "intendedStatus": "ACTIVE",
    "account": "urn:li:sponsoredAccount:506316595"
}

    Update a Dynamic Job Ad Creative

    POST https://api.linkedin.com/rest/creatives/{sponsoredCreative-urn}

    {
    "patch": {
        "$set": {
            "content": {
                "jobs": {
                    "headline": {
                        "preApproved": "MEMBER_NEED_A_NEW_CHALLENGE_WE_CAN_HELP"
                    },
                    "buttonLabel": {
                        "preApproved": "CAREERS_AT_COMPANY"
                    },
                    "showMemberProfilePhoto": false,
                    "organizationName": "organizationName",
                    "logo": "urn:li:image:C4E22AQExxAnf-VY49w"
                }
            }
        }
    }
}

    Sample Response

    A successful response returns a 204 No Content.

    Delete a Dynamic Job Ad Creative

    DELETE https://api.linkedin.com/rest/creatives/{sponsoredCreative-urn}

    A successful response returns a 204 No Content.

    Batch Create Dynamic Job Ads

    POST https://api.linkedin.com/rest/creatives

    {
    "elements": [
        {
            "content": {
                "jobs": {
                    "organizationName": "Test Company Name",
                    "logo": "urn:li:image:C4E22AQExxAnf-VY49w",
                    "headline": {
                        "preApproved": "MEMBER_NEED_A_NEW_CHALLENGE_WE_CAN_HELP"
                    },
                    "buttonLabel": {
                        "preApproved": "CAREERS_AT_COMPANY"
                    },
                    "showMemberProfilePhoto": true
                }
            },
            "campaign": "urn:li:sponsoredCampaign:190357284",
            "intendedStatus": "ACTIVE"
        },
        {
            "content": {
                "jobs": {
                    "organizationName": "Test Company Name",
                    "logo": "urn:li:image:C4E22AQExxAnf-VY49w",
                    "headline": {
                        "custom": "MEMBER_NEED_A_NEW_CHALLENGE_WE_CAN_HELP"
                    },
                    "buttonLabel": {
                        "preApproved": "CAREERS_AT_COMPANY"
                    },
                    "showMemberProfilePhoto": true
                }
            },
            "campaign": "urn:li:sponsoredCampaign:190357284",
            "intendedStatus": "ACTIVE"
        }
    ]
}

    Sample Response

    {
    "elements": [
        {
            "location": "/partnerApiCreatives/urn%3Ali%3AsponsoredCreative%3A160731524",
            "status": 201,
            "id": "urn:li:sponsoredCreative:160731524"
        },
        {
            "location": "/partnerApiCreatives/urn%3Ali%3AsponsoredCreative%3A160731534",
            "status": 201,
            "id": "urn:li:sponsoredCreative:160731534"
        }
    ]
}

    Batch Get Dynamic Job Ads

    GET 'https://api.linkedin.com/rest/creatives?ids=List({sponsoredCreative-urn1},{sponsoredCreative-urn2})'

    Sample Response

    {
    "results": {
        "urn:li:sponsoredCreative:160731534": {
            "servingHoldReasons": [
                "UNDER_REVIEW",
                "CAMPAIGN_STOPPED"
            ],
            "lastModifiedAt": 1643800364000,
            "lastModifiedBy": "urn:li:person:B1U4S2MZ-C",
            "content": {
                "jobs": {
                    "logo": "urn:li:image:C4E22AQExxAnf-VY49w",
                    "showMemberProfilePhoto": true,
                    "organizationName": "Test Company Name",
                    "headline": {
                        "custom": "MEMBER_NEED_A_NEW_CHALLENGE_WE_CAN_HELP"
                    },
                    "buttonLabel": {
                        "preApproved": "CAREERS_AT_COMPANY"
                    }
                }
            },
            "createdAt": 1643800364000,
            "isTest": false,
            "createdBy": "urn:li:person:B1U4S2MZ-C",
            "review": {
                "status": "PENDING"
            },
            "isServing": false,
            "campaign": "urn:li:sponsoredCampaign:190357284",
            "id": "urn:li:sponsoredCreative:160731534",
            "intendedStatus": "ACTIVE",
            "account": "urn:li:sponsoredAccount:506316595"
        },
        "urn:li:sponsoredCreative:160731524": {
            "servingHoldReasons": [
                "UNDER_REVIEW",
                "CAMPAIGN_STOPPED"
            ],
            "lastModifiedAt": 1643800364000,
            "lastModifiedBy": "urn:li:person:B1U4S2MZ-C",
            "content": {
                "jobs": {
                    "logo": "urn:li:image:C4E22AQExxAnf-VY49w",
                    "showMemberProfilePhoto": true,
                    "organizationName": "Test Company Name",
                    "headline": {
                        "preApproved": "MEMBER_NEED_A_NEW_CHALLENGE_WE_CAN_HELP"
                    },
                    "buttonLabel": {
                        "preApproved": "CAREERS_AT_COMPANY"
                    }
                }
            },
            "createdAt": 1643800364000,
            "isTest": false,
            "createdBy": "urn:li:person:B1U4S2MZ-C",
            "review": {
                "status": "PENDING"
            },
            "isServing": false,
            "campaign": "urn:li:sponsoredCampaign:190357284",
            "id": "urn:li:sponsoredCreative:160731524",
            "intendedStatus": "ACTIVE",
            "account": "urn:li:sponsoredAccount:506316595"
        }
    },
    "statuses": {
        "urn:li:sponsoredCreative:160731534": 200,
        "urn:li:sponsoredCreative:160731524": 200
    },
    "errors": {}
}

    Batch Update Dynamic Job Ads

    POST 'https://api.linkedin.com/rest/creatives?ids=List({sponsoredCreative-urn1},{sponsoredCreative-urn2})'

    {
    "entities": {
        "{sponsoredCreative-urn1}": {
            "patch": {
                "$set": {
                    "content": {
                        "jobs": {
                            "organizationName": "Test Company Name",
                            "logo": "urn:li:image:C4E22AQExxAnf-VY49w",
                            "headline": {
                                "custom": "CUSTOM"
                            },
                            "buttonLabel": {
                                "custom": "CUSTOM"
                            },
                            "showMemberProfilePhoto": false
                        }
                    }
                }
            }
        },
        "{sponsoredCreative-urn2}": {
            "patch": {
                "$set": {
                    "content": {
                        "jobs": {
                            "organizationName": "Test Company Name",
                            "logo": "urn:li:image:C4E22AQExxAnf-VY49w",
                            "headline": {
                                "custom": "CUSTOM"
                            },
                            "buttonLabel": {
                                "custom": "CUSTOM"
                            },
                            "showMemberProfilePhoto": false
                        }
                    }
                }
            }
        }
    }
}

    Sample Response

    {
    "results": {
        "urn:li:sponsoredCreative:160731534": {
            "status": 204
        },
        "urn:li:sponsoredCreative:160731524": {
            "status": 204
        }
    },
    "errors": {}
}

    Batch Delete Dynamic Jobs Ads

    DELETE 'https://api.linkedin.com/rest/creatives?ids=List({sponsoredCreative-urn1},{sponsoredCreative-urn2})'

    Sample Response

    {
    "results": {
        "urn:li:sponsoredCreative:160731884": {
            "status": 204
        },
        "urn:li:sponsoredCreative:160731874": {
            "status": 204
        }
    },
    "errors": {}
}

    Finders for Dynamic Job Ads

    GET 'https://api.linkedin.com/rest/creatives?campaigns=List(urn%3Ali%3AsponsoredCampaign%3A190357284)&intendedStatuses=List(ACTIVE)&q=criteria&sortOrder=ASCENDING'

    Sample Response

    {
    "paging": {
        "start": 0,
        "count": 2,
        "links": [],
        "total": 2
    },
    "elements": [
        {
            "servingHoldReasons": [
                "UNDER_REVIEW",
                "CAMPAIGN_STOPPED"
            ],
            "lastModifiedAt": 1643800073000,
            "lastModifiedBy": "urn:li:person:B1U4S2MZ-C",
            "content": {
                "jobs": {
                    "logo": "urn:li:image:C4E22AQExxAnf-VY49w",
                    "showMemberProfilePhoto": false,
                    "organizationName": "organizationName",
                    "headline": {
                        "preApproved": "MEMBER_NEED_A_NEW_CHALLENGE_WE_CAN_HELP"
                    },
                    "buttonLabel": {
                        "preApproved": "CAREERS_AT_COMPANY"
                    }
                }
            },
            "createdAt": 1643767858000,
            "isTest": false,
            "createdBy": "urn:li:person:B1U4S2MZ-C",
            "review": {
                "status": "PENDING"
            },
            "isServing": false,
            "campaign": "urn:li:sponsoredCampaign:190357284",
            "id": "urn:li:sponsoredCreative:160701894",
            "intendedStatus": "ACTIVE",
            "account": "urn:li:sponsoredAccount:506316595"
        },
        {
            "servingHoldReasons": [
                "UNDER_REVIEW",
                "CAMPAIGN_STOPPED"
            ],
            "lastModifiedAt": 1643791704000,
            "lastModifiedBy": "urn:li:person:B1U4S2MZ-C",
            "content": {
                "jobs": {
                    "logo": "urn:li:image:C4E22AQExxAnf-VY49w",
                    "showMemberProfilePhoto": false,
                    "organizationName": "organizationName",
                    "headline": {
                        "custom": "CUSTOM2"
                    },
                    "buttonLabel": {
                        "custom": "CUSTOM2"
                    }
                }
            },
            "createdAt": 1643791171000,
            "isTest": false,
            "createdBy": "urn:li:person:B1U4S2MZ-C",
            "review": {
                "status": "PENDING"
            },
            "isServing": false,
            "campaign": "urn:li:sponsoredCampaign:190357284",
            "id": "urn:li:sponsoredCreative:160712624",
            "intendedStatus": "ACTIVE",
            "account": "urn:li:sponsoredAccount:506316595"
        }
    ]
}

    Error Messages

    General creative errors are included here - Creatives error.