Create a new or update an existing LinkedIn Document Ad on the Metadata platform.
A LinkedIn Document Ad promotes a multi-page document (a PDF — e.g. a
whitepaper, ebook, report, or guide) natively in the LinkedIn feed.
Members preview the first few pages inline, then unlock the full
document (typically gated behind a lead form). It is LinkedIn-only.
IMPORTANT: This tool is ONLY for LinkedIn Document Ads
(channelType=LINKEDIN, adType=DOCUMENT). For IMAGE/GIF ads use
create_update_image_ad; for VIDEO ads use create_update_video_ad; for
CONVO use create_update_convo_ad; for Sponsored Messaging use
create_update_linkedin_message_ad.
BEHAVIOR:
- If `id` is NOT provided -> creates a new Document Ad.
- If `id` IS provided -> updates the existing Document Ad with that ID.
CREATIVE WORKFLOW (MUST DO BEFORE CALLING):
1. The document must already exist in the creative library as a
DOCUMENT asset. Find it with
`search_library_creatives_by_name(contentTypes="DOCUMENT")`, or
confirm a specific id with `fetch_creative_details`.
2. Pass that asset's integer id as `libraryId`. It MUST be a
DOCUMENT-type creative — an image or video id will be rejected
by LinkedIn. Unlike IMAGE/VIDEO ads there is NO display URL: the
gated document is the destination, so no link field is accepted.
CHARACTER LIMITS (mirror the LinkedIn ad limits the platform UI enforces):
- name <= 50 chars (ad name in the library)
- headline <= 200 chars (the headline shown with the document)
- text <= 3000 chars (the introductory text)
INPUT PARAMETERS:
- id (optional): Existing Document Ad ID. Provide to UPDATE; omit to CREATE.
- name (required, <= 50): Ad name in the library.
- libraryId (required): Integer id of the DOCUMENT creative in the
library (contentType=DOCUMENT). NOT an image/video id.
- headline (required, <= 200): Headline shown with the document.
- text (required, <= 3000): Introductory text shown with the document.
- ctaType (optional, default UNLOCK_FULL_DOCUMENT): the call-to-action.
UNLOCK_FULL_DOCUMENT is the document-gate CTA.
- maxPreviewPages (optional, default 1): how many pages of the document
are previewable before the unlock gate. Positive integer.
- completionStatus (optional, default DRAFT): "DRAFT" or "COMPLETED".
Use COMPLETED only when every required field is final.
WHEN TO USE:
- User asks to "create a LinkedIn Document Ad" / "whitepaper ad" /
"promote a PDF / ebook / report on LinkedIn".
- User wants to update an existing Document Ad.
WHEN NOT TO USE:
- Feed image / GIF ad -> create_update_image_ad
- Feed video ad -> create_update_video_ad
- Branching conversation flow -> create_update_convo_ad
- One-shot Sponsored Message -> create_update_linkedin_message_ad
EXAMPLE USAGE (Create):
create_update_document_ad(
name="Q3_Whitepaper_LI_Document",
libraryId=15791,
headline="The 2026 State of B2B Marketing",
text="Download our latest research on pipeline attribution.",
maxPreviewPages=2,
)
EXAMPLE USAGE (Update):
create_update_document_ad(
id=29144,
name="Q3_Whitepaper_LI_Document_v2",
libraryId=15791,
headline="The 2026 State of B2B Marketing (Updated)",
text="Now with fresh benchmarks.",
)
COMMON MISTAKES:
- Passing an IMAGE/VIDEO libraryId — the asset must be a DOCUMENT
(use search_library_creatives_by_name(contentTypes="DOCUMENT")).
- Passing a display / landing URL — Document Ads have no link field.
- Using this tool for a non-LinkedIn channel — Document Ads are LinkedIn-only.
