Endpoint

Method	Path
POST	/messages/request_message_generation

Message Types

Use the messageType values below in your message_sequence. Each step in the sequence can use one or more of these types.

Message Type	Description	Key (for message_sequence parameter)
Connection Request	Your opening move: a personalised message sent with your LinkedIn connection request. Establishes connection and explains why it would be useful to connect. Useful for differentiation in saturated markets (e.g. US, UK).	connection_request
First Follow Up	Your first proactive touchpoint after they accept. Says something relevant about them first, then explains how it relates to what you do. Best for driving toward a meeting, demo, or conversation. Reference the accepted connection, include a specific call-to-action, and send after the request is accepted.	first_follow_up
Current Stage Ambition	A taster of how your proposition can help the prospect achieve what they are most likely focused on, given their role and firmographics. Use when you want a dedicated message that highlights your value without the full proposition overview. The message body is generated from your proposition context.	stage_ambition
Share Material Message	Share some Thought Leadership, a Case Study or a Product Overview that provides immediate value and positions your expertise in a contextualised way for the prospect. Nurtures the relationship and demonstrates expertise. For best results, ensure the content is one of those 3 categories.	share_material
Hiring Activity Message	Derive insights about company objectives through the jobs they are hiring for right now, and position your proposition as an enabler to those objectives. Useful to offer meaningful help with company objectives rather than just selling your proposition. Works best for large companies with multiple open roles.	hiring_activity

Coming soon: industry_insight, proposition_summary, breakup, linkedin_post, re-engagement, youtube_content, trustpilot_reviews

Request

Request parameters

* = required

Required for all requests

Parameter	Type	Description
completion_notification_url*	string (URL)	Webhook URL to receive notification when message generation is complete
automation_tool_customer_id*	string	Your internal customer/account identifier
automation_tool_campaign_id*	string	Your internal campaign identifier
automation_tool_campaign_name*	string	Display name for the campaign (e.g. for your own reference)
proposition_company_name*	string	The name of the campaign proposition company (for personalization)
proposition_company_url*	string (URL)	The website of that company (must be valid HTTP/HTTPS)
message_sequence*	array of objects	Array of sequence steps. Each object must have `step` (integer, must start at 1) and `messageType` (string). For allowed messageType values, see table at top of page.
lead_data*	array	Array of lead objects (minimum 1 required)

Optional

Parameter	Type	Description
tone_preference	string	One of: formal, normal, or casual only. Default is normal if omitted.
signoff_name	string	If provided, generated messages are signed off with this name. If omitted, messages are signed off with `{{yourName}}` and you must replace that variable with the sender's name before use.

Required when using specific message types

Include the parameters below only when your message_sequence contains the corresponding message type.

`stage_ambition`

Parameter	Type	Description
job_title*	string	The job title of the prospect, used (in addition to their firmographics) to infer their current priorities.

`share_material`

Parameter	Type	Description
material_link*	string (URL)	URL to the material to share. The material should be a piece of Thought Leadership, a Case Study or a Product Overview - this is what enables the best performing message content.

`hiring_activity`

Parameter	Type	Description
hiring_location*	string	A single location (country) for where relevant roles are being hired right now. Must be a valid ISO 3166-1 country code (e.g. GB, US, DE).

Lead data object parameters

* = required

Parameter	Type	Description
automation_tool_lead_id*	string	Your internal lead/prospect identifier
lead_linkedin*	string (URL)	LinkedIn profile URL of the prospect
lead_company*	string	Company name where the prospect works
first_name*	string	Prospect's first name
last_name*	string	Prospect's last name
lead_company_website_url	string (URL)	Company website URL (optional)
lead_specified_url	string (URL)	Specific URL for research (optional). If provided, this URL is used instead of lead_company_website_url. When both are given, lead_specified_url takes precedence.

Notes

The message_sequence array defines the order of message types to generate. Each element is an object with step (integer) and messageType (string). Sequences must always start with step 1.
When message_sequence includes share_material, you must provide material_link (URL to the material to share).
When message_sequence includes hiring_activity, you must provide hiring_location: a single ISO 3166-1 country code (e.g. GB, US, DE).
When message_sequence includes stage_ambition, you must provide job_title (e.g. the role you are targeting or the sender's role context).
The completion_notification_url is required so you receive webhook notifications when generation completes.
Sign-off: If you provide signoff_name, generated messages are signed off with that name. If you omit it, messages end with {{yourName}} and you must replace that variable with the sender's name before sending.
All lead_data entries must include the required fields listed above.
The API returns a secure_request_id that you use with the Retrieve Messages API to fetch the generated messages.
If you request the same message type for the same lead (same automation_tool_lead_id) and it has already been generated, a new message is not generated and no additional credit is used.

Example request (JSON body)

{
  "completion_notification_url": "https://your-webhook-endpoint.com/webhook",
  "automation_tool_customer_id": "customer_12345",
  "automation_tool_campaign_id": "campaign_67890",
  "automation_tool_campaign_name": "Campaign 1 - North America",
  "proposition_company_name": "Acme Corporation",
  "proposition_company_url": "https://www.acmecorp.com",
  "message_sequence": [{ "step": 1, "messageType": "connection_request" }, { "step": 2, "messageType": "first_follow_up" }],
  "tone_preference": "formal",
  "signoff_name": "Sarah",
  "lead_data": [
    {
      "automation_tool_lead_id": "lead_001",
      "lead_linkedin": "https://linkedin.com/in/john-doe",
      "lead_company": "Tech Solutions Inc",
      "first_name": "John",
      "last_name": "Doe",
      "lead_company_website_url": "https://www.techsolutions.com",
      "lead_specified_url": null
    },
    {
      "automation_tool_lead_id": "lead_002",
      "lead_linkedin": "https://linkedin.com/in/jane-smith",
      "lead_company": "Digital Innovations LLC",
      "first_name": "Jane",
      "last_name": "Smith",
      "lead_company_website_url": "https://www.digitalinnovations.com",
      "lead_specified_url": null
    }
  ]
}

Response

On success (200), the response includes message and secure_request_id. Use secure_request_id to retrieve the generated messages (see Retrieve Messages API) and to identify the request in completion webhook payloads.

Asynchronous process: Message generation runs in the background. The API returns immediately; generation continues after the response. To get all messages when they are ready, use the completion notification webhook (you must provide completion_notification_url in this request). You can also call the Retrieve Messages API at any time, but if you call it before generation has finished, you will receive only the messages that have been generated so far — not necessarily all of them.

Response (200)

{
  "message": "Success",
  "secure_request_id": "3d68ae3b-5957-454d-be1c-8731a4f877f6"
}

Request Message Generation API