LinkedIn API: How to Post Clickable Links with Custom Images (PHP Guide)

How Did We Discover the LinkedIn API Image and URL Conflict?

During a recent project for a marketing SaaS platform, our team was tasked with building an automated content syndication engine. The goal was to allow users to schedule and publish rich media content directly to their social media profiles, including LinkedIn. We built the backend using PHP and cURL to handle the OAuth 2.0 authentication and payload delivery.

While the initial integration appeared successful—we successfully authenticated with the required scopes (w_member_social, openid, profile, email) and successfully uploaded images via LinkedIn’s media service to generate asset URNs—a critical issue surfaced during User Acceptance Testing (UAT). Users reported that when they created a post with both an uploaded photo and a target URL, the resulting LinkedIn post either displayed the image but was unclickable, or was clickable but lacked the custom high-resolution image.

In automated social media marketing, a post that lacks a clickable rich media card severely degrades the Click-Through Rate (CTR). Resolving this required a deep dive into LinkedIn’s User Generated Content (UGC) API schema constraints. This challenge inspired the following architectural breakdown so other teams can avoid the same payload formatting mistakes when scaling automated publishing pipelines.

What Was the Business Context and Architectural Challenge?

The core business requirement was simple: allow a user to upload a custom promotional image, write an engaging caption, and attach a destination URL. When pushed to LinkedIn, the post needed to appear as a clickable “Link Card” where clicking the custom image redirected the user to the specified landing page.

From an architectural standpoint, this required a multi-step API interaction within our PHP worker:

• • Initiate a media upload session to LinkedIn to acquire an upload URL.

• • Push the binary image data to the provided URL via a PUT request.

• • Retrieve the final urn:li:digitalmediaAsset:CODE representing the uploaded image.

• • Construct a JSON payload binding the text, the URL, and the image URN, and POST it to the /v2/ugcPosts endpoint.

The problem materialized in the final step. LinkedIn’s API enforces strict categorization of content types via the shareMediaCategory property, and attempting to merge the behaviors of an “Image Post” and an “Article Post” caused silent failures and unexpected API rejections. When scaling such platforms, companies often look to hire software developer teams capable of navigating these strict third-party API nuances.

What Exactly Went Wrong with the API Payload?

Our initial JSON payload structure assumed that we could simply define the media category and provide both the image URN and the destination URL within the media array. Here is a sanitized example of the problematic payload structure we initially generated:

{
    "author": "urn:li:person:SUBCODE",
    "lifecycleState": "PUBLISHED",
    "specificContent": {
        "com.linkedin.ugc.ShareContent": {
            "shareCommentary": {
                "text": "Platform updates are live! - share commentary"
            },
            "shareMediaCategory": "IMAGE",
            "media": [
                {
                    "status": "READY",
                    "description": {
                        "text": "Read the full release notes here."
                    },
                    "media": "urn:li:digitalmediaAsset:MEDIACODE",
                    "title": {
                        "text": "Q3 Platform Release Updates"
                    },
                    "originalUrl": "https://example-saas-platform.com/release-notes"
                }
            ]
        }
    },
    "visibility": {
        "com.linkedin.ugc.MemberNetworkVisibility": "PUBLIC"
    }
}

When executing this payload via cURL, the symptoms varied based on the shareMediaCategory value:

• Scenario A (shareMediaCategory = “IMAGE”): The API returned a 201 Created success code. The post appeared on LinkedIn featuring the custom uploaded image. However, the originalUrl parameter was entirely ignored. The image was not clickable, frustrating users who wanted to drive traffic to their landing pages.
• Scenario B (shareMediaCategory = “ARTICLE”): Suspecting we needed an article link type, we changed the category to ARTICLE but left the array structure unchanged. The API immediately rejected the request with a 400 Bad Request error, pointing to an invalid value on the "media": "urn:li:digitalmediaAsset:MEDIACODE" line.
• Scenario C (Fallback): If we removed the media URN line entirely while using ARTICLE, the post succeeded and the URL was clickable. However, LinkedIn would randomly scrape the target website’s Open Graph (OG) tags for a thumbnail, completely bypassing the custom image the user had carefully uploaded.

How Did We Evaluate and Approach the Solution?

To deliver the required functionality, we needed to find the exact schema structure that permitted an uploaded asset URN to act as the visual thumbnail for an article link. We evaluated several approaches to bypass or fix the limitation.

What Alternative Approaches Did We Consider?

Approach 1: Relying Exclusively on Open Graph Meta Tags

We considered abandoning custom image uploads and forcing users to ensure their landing pages had correct og:image tags. We would simply pass the URL and let LinkedIn’s crawler do the work. We rejected this because users frequently promote third-party links or dynamic URLs where they do not control the meta tags. They needed granular control over the post’s visual presentation.

Approach 2: Appending the Link to a Pure Image Post

We tested keeping shareMediaCategory as IMAGE and appending the target URL into the shareCommentary text body. While technically functional, the visual image card itself was not clickable. Modern social media engagement heavily relies on the entire visual real estate acting as a click-through trigger. This resulted in unacceptable UX.

Approach 3: Restructuring the UGC Article Schema

We decided to dive deeper into the LinkedIn developer documentation for the UGC Posts API. We discovered that while an IMAGE post accepts the asset URN directly under the media property, an ARTICLE post uses an entirely different nested structure. For an ARTICLE, the primary asset is the URL itself (originalUrl), and any custom imagery must be explicitly nested within a thumbnails array. This type of investigative debugging is exactly why tech leaders hire php developers for scalable data systems to handle complex enterprise API integrations.

What Did the Final Implementation Look Like?

The solution required us to adjust our backend PHP logic to dynamically reshape the JSON payload based on whether the user was attempting to post a pure image gallery or a clickable link card. When both an image and a URL were present, we forced the application to generate an ARTICLE payload with a nested thumbnail.

Here is the corrected and sanitized JSON schema that successfully delivered both a custom uploaded image and a clickable destination URL:

{
    "author": "urn:li:person:YOUR_ID",
    "lifecycleState": "PUBLISHED",
    "specificContent": {
        "com.linkedin.ugc.ShareContent": {
            "shareCommentary": {
                "text": "Platform updates are live! Click the card to read the full release notes."
            },
            "shareMediaCategory": "ARTICLE",
            "media": [
                {
                    "status": "READY",
                    "description": {
                        "text": "Read the full release notes here."
                    },
                    "originalUrl": "https://example-saas-platform.com/release-notes",
                    "title": {
                        "text": "Q3 Platform Release Updates"
                    },
                    "thumbnails": [
                        {
                            "image": "urn:li:digitalmediaAsset:YOUR_MEDIA_URN"
                        }
                    ]
                }
            ]
        }
    },
    "visibility": {
        "com.linkedin.ugc.MemberNetworkVisibility": "PUBLIC"
    }
}

To execute this reliably in our PHP environment, we encapsulated the cURL execution in a robust service class that handled token management and error reporting:

function publishLinkedInArticle($accessToken, $payloadJson) {
    $endpoint = "https://api.linkedin.com/v2/ugcPosts";
    
    $ch = curl_init($endpoint);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $payloadJson);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "Authorization: Bearer " . $accessToken,
        "Content-Type: application/json",
        "X-Restli-Protocol-Version: 2.0.0"
    ]);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    
    if (curl_errno($ch)) {
        throw new Exception("cURL Error: " . curl_error($ch));
    }
    
    curl_close($ch);
    
    if ($httpCode >= 200 && $httpCode < 300) {
        return json_decode($response, true);
    } else {
        throw new Exception("LinkedIn API Error ($httpCode): " . $response);
    }
}

What Are the Core Lessons for Engineering Teams?

Working with enterprise-grade social APIs requires precision. Here are the actionable insights our engineering team extracted from this integration challenge:

• Strict Schema Validation is Mandatory: Third-party APIs often share object structures across different content types but process them uniquely. Do not assume an array structure that works for an IMAGE category will be parsed the same way for an ARTICLE category.
• Decouple Media Logic from Publishing Logic: The act of uploading a file and acquiring a URN should be a distinct, self-contained service. This allows your publishing service to treat the URN as a simple string, making it easier to nest it inside thumbnails or media depending on the final post type.
• Monitor Provider Documentation Closely: LinkedIn periodically updates its data models. Knowing the difference between the legacy UGC Posts API and the newer Posts API ensures forward compatibility.
• Do Not Rely on Implied API Behavior: Just because an API returns a 201 Created status (as it did when we sent a URL in an IMAGE payload) does not mean the payload was processed as you intended. Always verify the output on the actual platform.
• Implement Detailed cURL Logging: Capturing HTTP status codes alongside raw response bodies is crucial for diagnosing 400 Bad Request errors. Without the raw response indicating that the media URN line was invalid, diagnosing the schema mismatch would have taken significantly longer.

For businesses looking to build reliable, heavily integrated platforms, choosing to hire api developers for production deployment ensures these external systems communicate flawlessly without degrading the end-user experience.

How Can We Summarize This API Integration Journey?

Successfully posting to LinkedIn using PHP and cURL with both custom imagery and actionable URLs ultimately comes down to understanding the API’s categorical constraints. By shifting our mindset from “attaching a URL to an image” to “attaching a custom thumbnail to an article,” we easily realigned our payload to meet LinkedIn’s UGC requirements. Ensuring robust error handling and payload structuring creates a resilient automated publishing pipeline that marketing teams can rely on. If your organization is facing similar integration hurdles or requires dedicated engineering expertise to scale your platforms, feel free to contact us.

Social Hashtags

#SoftwareDevelopment #BackendDevelopment #PHPDeveloper #RESTAPI #OAuth #cURL #JSON #Automation #MarketingAutomation #SaaS #DeveloperTips #Coding #TechBlog #OpenSource #Programming