API Reference

Endpoint

POST https://personalize.marketing/api/v1/personalize-api

Authentication

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Request Body

Field	Type	Required	Description
`profile_url`	string	Yes	LinkedIn, Instagram, or TikTok profile URL (e.g., `https://linkedin.com/in/username`)
`template`	string	Yes	Your message template. Must contain at least one `{{instruction}}` placeholder (e.g., `{{first name}}`, `{{topic from recent post}}`)
`ai_instructions`	string	No	Custom instructions for the AI (e.g., "Keep it casual", "Be professional")
`brand_context`	string	No	Describe your brand so the AI picks relevant posts to reference
`enable_variations`	boolean	No	Rephrase each message uniquely to avoid spam detection
`enable_brand_fit_score`	boolean	No	Returns a 1-10 score of how well the prospect fits your brand
`include_profile_report`	boolean	No	Returns a detailed analysis of the prospect
`include_raw_data`	boolean	No	Returns the raw profile data used for personalization (see warning below)

About include_raw_data: This field returns the raw profile data for informational/debugging purposes only. Do not rely on this data structure - it changes frequently as we improve our algorithm. Use it to inspect what data is available, but do not build integrations that depend on its format.

Response

Success Response

{
  "success": true,
  "personalized_text": "Hey Arnold! Saw your post about building The Pump app...",
  "profile_url": "https://linkedin.com/in/arnold-schwarzenegger/",
  "brand_fit_score": 9,
  "profile_report": "## Overview\nEntrepreneur and actor...",
  "raw_data": { "profile": { ... }, "posts": [ ... ] }
}

Field	Type	Description
`success`	boolean	Always `true` on success
`personalized_text`	string	Your template with all `{{instruction}}` placeholders replaced
`profile_url`	string	The original profile URL
`brand_fit_score`	number	1-10 score (only if `enable_brand_fit_score: true`)
`profile_report`	string	Markdown report (only if `include_profile_report: true`)
`raw_data`	object	Raw profile data (only if `include_raw_data: true`) - structure may change

Error Response

{
  "success": false,
  "error": {
    "code": "PROFILE_NOT_FOUND",
    "message": "Could not find the profile"
  },
  "profile_url": "https://instagram.com/nonexistent"
}

Error Codes

Code	Description
`INVALID_INPUT`	Missing required fields or invalid format
`INVALID_URL`	URL could not be parsed
`UNSUPPORTED_PLATFORM`	Only LinkedIn, Instagram, and TikTok are supported
`PROFILE_NOT_FOUND`	Profile doesn't exist
`PROFILE_PRIVATE`	Profile is private and cannot be analyzed
`DATA_FETCH_FAILED`	Failed to fetch profile data
`AI_GENERATION_FAILED`	AI failed to generate personalized message
`INTERNAL_ERROR`	Unexpected server error

Rate Limits

Requests may take up to 300 seconds to complete
Set your HTTP client timeout to at least 300 seconds (5 minutes)

Supported Platforms

Platform	URL Format
LinkedIn	`https://linkedin.com/in/username`
Instagram	`https://instagram.com/username`
TikTok	`https://tiktok.com/@username`

API Reference

On this page