Request Message Generation API

Submit a list of leads and your proposition details to request personalised LinkedIn messages. Provide a completion notification URL to receive a webhook when generation is finished.

Endpoint

Method	Path
POST	/request_message_generation

Request

Request parameters

* = required

Parameter	Type	Description
All fields are mandatory except lead_specified_url and lead_company_website_url on each lead, and signoff_name. If `message_sequence` includes an entry with `messageType` `share_material`, `material_link` is also mandatory. If `message_sequence` includes `hiring_activity`, `hiring_location` is also mandatory.
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). Allowed messageType values: connection_request, first_follow_up, share_material, hiring_activity. Coming soon: industry_insight, proposition_summary, breakup, linkedin_post, re-engagement, youtube_content, trustpilot_reviews
material_link*	string (URL)	URL to the material to share. Required when `message_sequence` includes an entry with `messageType` `share_material`. The material should be something where the implicit conclusion is "buy our product" - this is what enables the best performing message content.
hiring_location*	string	A single location (country) for hiring-activity message inference. Required when `message_sequence` includes `hiring_activity`. Must be a valid ISO 3166-1 country code (e.g. `GB`, `US`, `DE`).
tone_preference	string	Optional. One of: formal, normal, or casual only. Default is normal if omitted.
signoff_name	string	Optional. 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.
lead_data*	array	Array of lead objects (minimum 1 required)

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).
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