Retrieve Messages API

Fetch the generated messages for a request. Send the secure_request_id returned from the Request Message Generation API to retrieve messages (and metadata) for that request. Message generation is asynchronous: if you call Retrieve Messages before the Request Message Generation process has completed, you will receive any messages that have been generated so far, but not all messages may be ready yet. Use the completion notification webhook to know when the full batch is done, then call this API to get all messages.

Endpoint

Method	Path
GET	/retrieve_messages

Headers: Api-Key: your_api_key_here, Content-Type: application/json

Request

Request parameters

* = required

Parameter	Type	Description
request_message_generation_secure_request_id*	string (UUID)	The secure_request_id returned from the Request Message Generation API (/request_message_generation)

Notes

The request_message_generation_secure_request_id is the secure_request_id value returned in the success response from the Request Message Generation API.
The Api-Key header must contain a valid, non-revoked API key.
Async behaviour: If you call this API before message generation has completed, you receive 202 and only the messages generated so far. Check metadata.generation_status (in_progress vs complete) and metadata.status_message, or compare metadata.generated_messages_count with metadata.requested_messages_count. Wait for the completion webhook or call again later for the full set.
The response returns one object per lead in campaign.leads_data; message fields may be null for leads or message types not yet generated. When some messages could not be generated, check metadata.failed_messages_reason for the reason; on the lead, only no_job_posts may be present — see 200 OK — Complete (some messages failed).

Example request (JSON body)

{
  "request_message_generation_secure_request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Response

The API returns 202 when message generation is still in progress (partial results) and 200 when generation is complete. The response body includes metadata, account, and campaign. Within metadata: generation_status is in_progress or complete; status_message describes the state; requested_messages_count, generated_messages_count, failed_messages_count, and failed_messages_reason report progress and failures. The campaign.leads_data array contains one object per lead, with message fields matching the message_sequence; fields may be null when not yet generated or when generation failed.

202 Accepted — In progress (partial results)

Scenario: Message generation is still running. The response includes whatever messages have been generated so far. metadata.generation_status is in_progress.

200 OK — Complete (all messages generated)

Scenario: All requested messages were successfully generated.

200 OK — Complete (some messages failed)

Scenario: Generation is complete but some requested messages failed to generate. No credits are deducted for failed prospects.

When some messages could not be generated, the prospect is still included in campaign.leads_data. Check failed_messages_reason for the reason(s) failures occurred (e.g. relevant research information not found, no hiring activity). On the lead object, the only notice field that may be present is no_job_posts. In all failure cases the prospect is counted in failed_messages_count and no credits are used.

Error response examples

Validation error (e.g. 422), Unauthorized (401):

202 — Partial results

{
  "metadata": {
    "request_message_generation_api_request_secure_request_id": "550e8400-e29b-41d4-a716-446655440000",
    "retrieve_messages_api_request_secure_request_id": "660e8400-e29b-41d4-a716-446655440001",
    "generation_status": "in_progress",
    "status_message": "Message generation is still in progress. Data shown is partial. Please wait for webhook notification or check again later.",
    "requested_messages_count": 10,
    "generated_messages_count": 3,
    "failed_messages_count": null,
    "failed_messages_reason": "Message generation is still in progress. The failed messages count will be available once generation is complete."
  },
  "account": {
    "automation_tool_customer_id": "customer_12345"
  },
  "campaign": {
    "automation_tool_campaign_id": "campaign_67890",
    "automation_tool_campaign_name": "Campaign 1 - North America",
    "message_sequence": [{ "step": 1, "messageType": "connection_request" }, { "step": 2, "messageType": "first_follow_up" }],
    "leads_data": [
      {
        "external_prospect_id": "lead_001",
        "linkedin": "https://linkedin.com/in/john-doe",
        "outreach_message": "Hi John, I noticed your work at Acme Corp...",
        "first_follow_up_message": null
      },
      {
        "external_prospect_id": "lead_002",
        "linkedin": "https://linkedin.com/in/jane-smith",
        "outreach_message": null,
        "first_follow_up_message": null
      }
    ]
  }
}

Retrieve Messages API