Share via

Documents API

  • Article

Warning

Deprecation Notice
The Marketing Version 202310 (Marketing October 2023) and earlier versions (excluding 202306 and 202307) have been sunset. Additionally, the unversioned APIs will 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.

Documents API makes it easier for you to manage Document assets and create Document ads.

Permissions

Permission Description
w_organization_social Post, comment, and like posts on behalf of an organization. Restricted to the company admin, DSC poster, or content admin.
r_organization_social Retrieve your organizations' posts, including any comments, likes and other engagement data with AUTHOR injection.
w_member_social Post, comment, and like posts on behalf of authenticated member.
r_member_social Retrieve posts, comments, reactions, and other engagement data on behalf of authenticated member.
rw_ads Create ads and creatives for a sponsored account.
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

The following permission checks are performed when uploading a document:

  • For documents with company URN owners, the caller must have ADMIN or DSC permissions for the company page.
  • For documents with SponsoredContentAccount URN owners, all GET's and UPDATE's are permitted.
  • For documents with person URN owners, the caller must match the document owner.

Invalid permissions results in the following API response:

{
    "message": "Accessing this document resource is forbidden. Please check your permissions for this resource",
    "status": 403
}

Important

The file size cannot exceed 100MB and 300 pages. The following file types are supported: PPT, PPTX, DOC, DOCX, and PDF.

Schema

Note

All APIs require the request headers LinkedIn-Version: {Version in YYYYMM format} and X-Restli-Protocol-Version: 2.0.0. Refer to the Protocol Versions page to learn more about Rest.li Protocol 2.0.0.

Field Name Type Description Required
downloadUrl URL Public URL to download/view the media asset. Is empty if the media asset isn't available, failed processing, etc. No
downloadUrlExpiresAt Time Milliseconds since the epoch (1970-01-01 00:00 UTC) when the identifier expires. If not present, it might never expire but there's no guarantee. Unless the use case has a security+legal exception, all URLs have an expiration time. If they don't, they can still expire because URLs are signed, and the sign keys might be rotated. If a non expiring URL was signed with a key that gets invalidated, it essentially expires. No
id DocumentUrn Unique URN for an Document. Synthetic key that should not be allowed during the creation of a Document. The field is read only and derived to be populated internally. Yes
owner URN The URN of the entity that owns this asset. It can be a person(urn:li:person:123), organization(urn:li:organization:123) or sponsoredAccount(urn:li:sponsoredAccount:123) URN Yes
status MediaStatus PROCESSING Asset is processing to generate missing artifacts. PROCESSING_FAILED - Processing failed due to client error such as file size too large, unsupported file format, internal error (e.g., performance issue, database error, network failure), or other issue. AVAILABLE - All of the recipe's required artifacts are ready. The asset is available to be served. WAITING_UPLOAD Waiting for client to upload source file or uploading process to be completed. No
initializeUploadRequest.owner URN URN of the entity that owns this asset. Can be a person(urn:li:person:123), or organization(urn:li:organization:123) URN Yes

Managing Document Asset

Uploading an Document

Initialize Document Upload

Use the initializeUpload action to register the upload. When you initialize, you declare the upcoming upload. Use the upload URL to upload the document.

Note

SYNCHRONOUS_UPLOAD is not supported in Documents API.

Sample Request
POST https://api.linkedin.com/rest/documents?action=initializeUpload

{
  "initializeUploadRequest": {
        "owner": "urn:li:organization:1234567"
  }
}
Sample Response
{
   "value": {
       "uploadUrlExpiresAt": 1650567510704,
       "uploadUrl": "https://www.linkedin.com/dms-uploads/D5510AQHXjcP8QBYD9A/ads-uploadedDocument/0?ca=vector_ads&cn=uploads&sync=0&v=beta&ut=36ezHi_Pod5aM1",
       "document": "urn:li:document:C5F10AQGKQg_6y2a4sQ"
   }
}

Upload the Document

Using the uploadUrl returned from the previous step, upload the document.

Note

Documents uploaded with the Documents API can be reused across different document and document ad formats. For example, a document can be used in a single document ad and a carousel ad and does not require separate document uploads.

Sample curl Request
curl -i --upload-file ~/Desktop/Mydoc.pdf -H 'Authorization: Bearer Redacted' "https://www.linkedin.com/dms-uploads/D5510AQHXjcP8QBYD9A/ads-uploadedDocument/0?ca=vector_ads&cn=uploads&sync=0&v=beta&ut=36ezHi_Pod5aM1"
Sample Response
HTTP/2 201 
server: Play
set-cookie: lang=v=2&lang=en-us; Path=/; Domain=api.linkedin.com
date: Wed, 16 Oct 2019 06:25:12 GMT
content-length: 0
x-li-proto: http/2
report-to: {"group":"network-errors","max_age":2592000,"endpoints":[{"url":"https://www.linkedin.com/li/rep"}],"include_subdomains":true}
nel: {"report_to":"network-errors","max_age":1296000,"success_fraction":0.0001,"failure_fraction":1,"include_subdomains":true}
x-li-uuid: slguD4sMzhUwATrTkisAAA==
set-cookie: lidc="b=ETB86:g=301:u=12:i=1571207079:t=1571261189:s=AQGEngFr_Vc-bGAR4gREsIou-eLZon31"

GET a single document

GET https://api.linkedin.com/rest/documents/urn:li:document:D5510AQHXjcP8QBYD9A

Sample Response

{
    "owner": "urn:li:organization:1234567",
    "downloadUrlExpiresAt": 1676584800000,
    "downloadUrl": "https://media.licdn.com/dms/document/D5510AQFx87994pYx0Q/ads-document-pdf-analyzed/0/1683274701806?e=1683921600&v=beta&t=JAT9bwclvaFdZOCYO0V7CwgfbaZJAouAeE9iMKdsAEM",
    "id": "urn:li:document:D5510AQFx87994pYx0Q",
    "downloadUrlExpiresAt": 1679083200000,
    "status": "AVAILABLE"
}

Batch get documents

GET https://api.linkedin.com/rest/documents?ids=List(urn%3Ali%3Adocument%3AD5510AQFx87994pYx0Q,urn%3Ali%3Adocument%3AC4E10AQFgOYeVoHFeBw)

Sample Response

{
    "results": {
        "urn:li:document:C5F10AQGKQg_6y2a4sQ": {
            "owner": "urn:li:organization:1234567",
            "downloadUrlExpiresAt": 1676584800000,
            "downloadUrl": "https://media.licdn.com/dms/document/D5510AQFx87994pYx0Q/ads-document-pdf-analyzed/0/1683274701806?e=1683921600&v=beta&t=JAT9bwclvaFdZOCYO0V7CwgfbaZJAouAeE9iMKdsAEM",
            "id": "urn:li:document:D5510AQFx87994pYx0Q",
            "downloadUrlExpiresAt": 1679083200000,
            "status": "AVAILABLE"
        },
        "urn:li:document:C4E10AQFgOYeVoHFeBw":
        {
            "owner": "urn:li:organization:1234567",
            "downloadUrlExpiresAt": 1676584800000,
            "downloadUrl": "https://media.licdn.com/dms/document/C4E10AQFgOYeVoHFeBw/ads-document-pdf-analyzed/0/1683274701806?e=1683921600&v=beta&t=JAT9bwclvaFdZOCYO0V7CwgfbaZJAouAeE9iMKdsAEM",
            "id": "urn:li:document:C4E10AQFgOYeVoHFeBw",
            "status": "WAITING_UPLOAD"
        }
    },
    "statuses":
    {
        "urn:li:document:D5510AQFx87994pYx0Q": 200,
        "urn:li:document:C4E10AQFgOYeVoHFeBw": 200
    },
    "errors":
    {}
}

Managing Document content

Create Document content

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

{
    "author": "urn:li:organization:1234567",
    "commentary": "test strings!",
    "visibility": "PUBLIC",
    "distribution": {
        "feedDistribution": "MAIN_FEED",
        "targetEntities": [],
        "thirdPartyDistributionChannels": []
    },
    "content": {
        "media": {
            "title":"Example.pdf",
            "id": "urn:li:document:D5510AQFx87994pYx0Q"
        }
    },
    "lifecycleState": "PUBLISHED",
    "isReshareDisabledByAuthor": false
}

Sample Response

A successful response returns a 201 Created HTTP status code and the ID in the x-linkedin-id response header.

Get Document content

You can retrieve document content associated with a Post performing GET call to the Posts API on a post that was created with document content. Example post ID: urn:li:share:6876614985750310912

GET https://api.linkedin.com/rest/posts/{postId}

Sample Response

{
    "lifecycleState": "PUBLISHED",
    "publishedBy": "urn:li:person:abcdefg",
    "lastModifiedAt": 1639512853791,
    "visibility": "PUBLIC",
    "publishedAt": 1639512774391,
    "author": "urn:li:company:1234567",
    "lastModifiedBy": "urn:li:csUser:2",
    "distribution": {
        "feedDistribution": "MAIN_FEED",
        "thirdPartyDistributionChannels": []
    },
    "content": {
        "media": {
            "taggedEntities": [],
            "id": "urn:li:document:D5510AQFx87994pYx0Q",
            "title": "Example1.pdf"
        }
    },
    "lifecycleStateInfo": {
        "isEditedByAuthor": false
    },
    "isReshareDisabledByAuthor": false,
    "createdAt": 1639512774185,
    "createdBy": "urn:li:person:abcdefg",
    "id": "urn:li:share:6876614985750310912",
    "commentary": "test strings!"
}

Batch Get Document Content

You can fetch multiple posts with document content by providing multiple post IDs.

POST https://api.linkedin.com/rest/posts?ids=List({encoded postId},{encoded postId})

Sample Response

{
   "results": {
       "urn:li:share:6927408039457087488": {
           "isReshareDisabledByAuthor": false,
           "createdAt": 1651622781932,
           "lifecycleState": "PUBLISHED",
           "lastModifiedAt": 1651622781932,
           "visibility": "PUBLIC",
           "publishedAt": 1651622781932,
           "author": "urn:li:organization:1234567",
           "id": "urn:li:share:6927408039457087488",
           "distribution": {
               "feedDistribution": "MAIN_FEED",
               "thirdPartyDistributionChannels": []
           },
           "content": {
               "media": {
                   "taggedEntities": [],
                   "id": "urn:li:document:D5510AQFx87994pYx0Q",
                   "title": "Example1.pdf"
               }
           },
           "commentary": "test strings!",
           "lifecycleStateInfo": {
               "isEditedByAuthor": false
           }
       },
       "urn:li:share:6927408326569783296": {
           "isReshareDisabledByAuthor": false,
           "createdAt": 1651622850346,
           "lifecycleState": "PUBLISHED",
           "lastModifiedAt": 1651622850346,
           "visibility": "PUBLIC",
           "publishedAt": 1651622850346,
           "author": "urn:li:organization:1234567",
           "id": "urn:li:share:6927408326569783296",
           "distribution": {
               "feedDistribution": "MAIN_FEED",
               "thirdPartyDistributionChannels": []
           },
           "content": {
               "media": {
                   "taggedEntities": [],
                   "id": "urn:li:document:C5F22AQFIMShx0jJbQw",
                   "title": "Example2.pdf"
               }
           },
           "commentary": "test strings!",
           "lifecycleStateInfo": {
               "isEditedByAuthor": false
           }
       }
   },
   "statuses": {
       "urn:li:share:6927408039457087488": 200,
       "urn:li:share:6927408326569783296": 200
   },
   "errors": {}
}

API Error Details

Code HTTP Status Code Error Message Description Resolution
INVALID_DOCUMENT_ID 400 This Document ID is invalid The requested Document ID is invalid. Pass the right Document ID.
INVALID_URN_ID 400 This Urn ID is invalid The format of an URN in the request is invalid. Check the format of any URNs in the request.
INVALID_URN_TYPE 400 {field} value {value} must be a {urnType} URN The URN needs to be a specific type. Check the type of any URNs in the request.
NOT_FOUND 404 Could not find entity The requested document asset is not found. Check whether the correct Document ID is passed.
DOCUMENT_FORBIDDEN 403 Accessing this document resource is forbidden. Please check your permissions for this resource. The request actor doesn't have the permissions to operate on the document resource on behalf of the document's owner. Obtain content creation permission from the designated owner of the document resource.