Introduction

The Upscale API lets you integrate personalised LinkedIn message generation with your systems. Send prospects, receive generated messages, and get notified when processing is complete.

Base URL

https://app.upscaleoutreach.com/api/v2

Authentication

Every request must include your API key in the Api-Key header. You can find your API keys in your account settings.

Header	Required	Description
Api-Key	Yes	Your API key value

Requests without a valid, non-revoked API key receive 401 Unauthorized.

Requests with a body (e.g. POST)

For endpoints that send a request body (such as Request Message Generation), send the body as JSON and include Content-Type: application/json in the headers. GET requests do not have a body and do not require this header.

Quick start

If you want to see some example messages immediately, use the curl below and paste in your API key. The response will include a secure_request_id; once generation has finished (or after a short wait), use the retrieve curl with that ID to fetch the generated messages.

Please note that if you would like to generate more messages after this, the system will de-duplicate same requests. It will also de-duplicate same message type requests for same lead id. Please change the lead id if you would like to generate new messages.

1. Request message generation

curl -X POST "https://app.upscaleoutreach.com/api/v2/messages/request_message_generation" \
  -H "Content-Type: application/json" \
  -H "Api-Key: <your-api-key-here>" \
  -d '{
  "completion_notification_url": "https://webhook.site/7f329acb-290c-4edb-9448-6066635883b3",
  "automation_tool_customer_id": "agency_id_xyz123456",
  "automation_tool_campaign_id": "campaign_xyz567890",
  "automation_tool_campaign_name": "Campaign A",
  "proposition_company_name": "Upscale Outreach",
  "proposition_company_url": "https://www.upscaleoutreach.com",
  "message_sequence": [{ "step": 1, "messageType": "connection_request" }, { "step": 2, "messageType": "first_follow_up" }, {"step": 3, "messageType": "share_material"}, { "step": 4, "messageType": "stage_ambition" }, {"step": 5, "messageType": "hiring_activity"}],
  "material_link_one": "https://www.upscaleoutreach.com/posts/personalise-linkedin-messages-at-scale-without-spending-hours",
  "hiring_location": "us",
  "signoff_name": "Charlie",
  "tone_preference": "normal",
  "lead_data": [
    {
      "automation_tool_lead_id": "lead_4d5e6",
      "lead_linkedin": "https://ee.linkedin.com/in/uku-taht",
      "lead_company": "Plausible",
      "first_name": "Uku",
      "last_name": "Taht",
      "lead_company_website_url": null,
      "lead_specified_url": null,
      "job_title": "Founder"
    },
    {
      "automation_tool_lead_id": "lead_1a2b3",
      "lead_linkedin": "https://www.linkedin.com/in/kathleen-bellah-842a8377",
      "lead_company": "Accenture",
      "first_name": "Kathleen",
      "last_name": "Bellah",
      "lead_company_website_url": null,
      "lead_specified_url": null,
      "job_title": "Senior Managing Director"
    }
  ]
}'

2. Retrieve the generated messages

Replace your_secure_request_id_here with the secure_request_id from the first response, and your_api_key_here with your API key.

curl --location --request GET 'https://app.upscaleoutreach.com/api/v2/messages/retrieve_messages?request_message_generation_secure_request_id=your_secure_request_id_here' \
--header 'Api-Key: your_api_key_here'

Errors

The API returns standard HTTP status codes with JSON response bodies.

Status code	Meaning
200	OK (success or duplicate)
202	Accepted (retrieve_messages, generation in progress)
401	Unauthorized (bad or revoked API key)
402	Payment required (request_message_generation only)
403	Forbidden (retrieve_messages only)
404	Not found (retrieve_messages only)
422	Unprocessable entity (validation)
429	Too many requests (rate limit)

Example error responses

Error responses are JSON with an error field describing the issue.

Status code	Scenario	Response body
401 Unauthorized	Invalid API key	{"error": "Unauthorized: Invalid API key"}
401 Unauthorized	Revoked API key	{"error": "Unauthorized: API key has been revoked"}
402 Payment Required	Insufficient credits	{"error": "Not enough credits remaining to complete this request. Please upgrade your plan or purchase a bundle."}
422 Unprocessable Entity	Validation error	{"error": "message_sequence must be an array"}
429 Too Many Requests	Rate limit exceeded	{"error": "Rate limit exceeded"}

Rate limits

Rate limits apply per account (across all API keys on that account) and help ensure fair usage and system stability.

What they do

Apply per account (across all API keys on that account).
Two kinds: API requests (number of calls) and messages requested (number of messages you request to be generated).
Windows: per calendar minute and per calendar day (UTC).
If any limit is exceeded, the API returns 429 Too Many Requests and the request is not processed.

Testing phase

Use when validating your integration or doing light load tests.

Limit type	Per minute	Per day
API requests	20	2,000
Messages requested	10	1,000

Normal production

Use for live traffic and higher throughput.

Limit type	Per minute	Per day
API requests	300	100,000
Messages requested	400	120,000

Future production

Higher throughput tier for accounts with elevated volume.

Limit type	Per minute	Per day
API requests	1,350	417,000
Messages requested	1,800	500,000

Rate limits will be increased in line with growing volumes on the platform.

APIs & Webhooks

Each API and webhook is documented on its own page. Use the sidebar or the links below.

Business process overview— End-to-end flow: campaign setup, connect notes, and message generation (who does what).
Request Message Generation API (POST)— Submit leads and proposition details to request personalised LinkedIn messages.
Retrieve Messages API (GET)— Fetch generated messages for a request using secure_request_id.
Get Sequences API (GET)— Retrieve available message sequences for campaigns.
Check API Key (GET)— Verify that an API key is valid and active (not revoked).
Check Credits (GET)— Get message allowance, credits used, and remaining credits.
Webhooks— Completion notification when message generation is finished; payload, retries and signature verification.

API Reference