Prospects

Create a prospect

Creates a prospect. Provide at least one of email, linkedinUrl, instagramUsername, or whatsappPhone — a prospect with no email address is still created and can be enrolled in LinkedIn, Instagram or WhatsApp campaigns. If one with the same email already exists it is merged and returned with alreadyExisted=true (HTTP 200); a brand-new prospect returns 201. Pass listId to drop the prospect into one of your lists; if a running campaign is linked to that list the prospect is auto-enrolled (continuous enrollment) — ideal for a website signup or popup form. Pass enrollInCampaignId instead to enroll into one specific campaign in the same call.

Required scope: prospects:write.

Requires a unique Idempotency-Key request header so retries never duplicate.

The prospect is always saved even if list attach or enrollment can't complete — the outcome is reported in the list / enrollment fields rather than failing the call.

listId echoes back the list you passed (or null), and list is { attached: true, enrolledCampaigns: <n> } on success, or { attached: false, error: "list_not_found", message: ... } if the list ID was wrong.

enrolledCampaigns counts the running campaigns linked to the list that the prospect was just folded into.

post/prospects

Request

  • Base URL: https://warmysender.com/api/v1
  • URL: https://warmysender.com/api/v1/prospects
  • Auth: HTTP bearer

Headers

Idempotency-Keystring required

A unique key (e.g. a UUID) that makes this write safe to retry. Reusing a key returns the original result; reusing it with a different body returns 409.

Request body

emailstring email

Prospect email (unique per workspace). Optional — provide email, linkedinUrl, instagramUsername, or whatsappPhone.

firstNamestring

First name.

lastNamestring

Last name.

companystring

Company.

rolestring

Job title / role.

phonestring

Phone number.

linkedinUrlstring uri

LinkedIn profile URL. Use for a LinkedIn-only prospect with no email.

instagramUsernamestring

Instagram handle (with or without the leading @, or a full instagram.com profile URL). Use for an Instagram-only prospect with no email.

whatsappPhonestring

WhatsApp number in any format (+49 171 234 5678, 0049…, bare digits, or a wa.me link). Stored in a single normalized form so the same person is never created twice. Use for a WhatsApp-only prospect with no email.

customFieldsobject

Arbitrary key/value pairs for personalization.

listIdstring

Add the created/updated prospect to this list. When a running campaign is linked to the list, the prospect is auto-enrolled into it (continuous enrollment). Find the list ID on the Lists page.

enrollboolean

When listId is set and a running campaign is linked to that list, auto-enroll the prospect into it. Set false to add to the list only, without enrolling. Defaults to true. Ignored when listId is omitted.

enrollInCampaignIdstring

Enroll the created/updated prospect into this specific campaign in the same call (bypasses lists). Requires the enrollments:write scope. Suppressed prospects are skipped.

Response

list_not_found — listId did not match a list in your workspace. The prospect is still saved; see list.error in the response body.

Changes

No recorded changes to this operation across all 1 revision of this API.