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 before it has completed, you will receive partial results; use the completion notification webhook to know when the full batch is done, then call this API to get all messages.

Endpoint

MethodPath
GET/messages/retrieve_messages

Request

Request parameters

* = required

ParameterTypeDescription
request_message_generation_secure_request_id*string (UUID)The secure_request_id returned from the Request Message Generation API (/messages/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. It is a UUID v4 in the usual hyphenated form: 8-4-4-4-12 hex digits, e.g. a8bd1fec-94dd-4d6a-b54d-2109994748ac.
  • 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_message_count with metadata.requested_message_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.

Example request (query parameter)

?request_message_generation_secure_request_id=your_secure_request_id_here

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_message_count, generated_message_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_message_count": 10,
    "generated_message_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
      }
    ]
  }
}