Distributions API

Quick Distribute

Send a survey to contacts in a single API call. This endpoint handles the full workflow:

1. Resolves/upserts contacts — by externalId, contactId, or email
2. Creates a mailing list — auto-generated for this distribution
3. Creates the distribution — with channel configuration, recipients, and personal links
4. Sends immediately — or schedules for later if scheduledAt is provided

Endpoint: POST /api/surveys/{surveyId}/distributions/quick

Hospital Workflow Example

A hospital HIS/EMR system sends a patient satisfaction survey after discharge:

curl -X POST "https://fikrr.diwakarmaurya.com/api/surveys/${SURVEY_ID}/distributions/quick" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "surveyId": "0195e3a1-0000-7000-8000-000000000001",
    "contacts": [
      {
        "externalId": "PAT-12345",
        "email": "john.doe@example.com",
        "firstName": "John",
        "lastName": "Doe",
        "embeddedData": {
          "department": "Cardiology",
          "visitDate": "2026-03-05",
          "attendingDoctor": "Dr. Smith",
          "dischargeDate": "2026-03-05"
        }
      }
    ],
    "channels": [
      {
        "channel": "email",
        "providerId": "PROVIDER_UUID",
        "templateId": "TEMPLATE_UUID"
      }
    ],
    "name": "Post-discharge CSAT - March 2026"
  }'

Request Parameters

Field	Type	Required	Description
surveyId	UUID	Yes	Target survey (also in URL path)
contacts	array	Yes	1–1,000 contacts to survey
channels	array	Yes	At least one channel configuration
channelMode	string	No	single (default) or multi
scheduledAt	ISO 8601 datetime	No	Schedule for future send; omit for immediate
settings	object	No	Distribution settings (see below)
name	string	No	Distribution name for reference (max 255 chars)

Contact fields

Field	Type	Required	Description
externalId	string	No*	External system identifier (max 255 chars)
contactId	UUID	No*	Existing contact ID
email	string	No*	Contact email
firstName	string	No	First name
lastName	string	No	Last name
phone	string	No	Phone number
embeddedData	object	No	Custom data accessible in survey via piped text ${contact:key}

*Each contact must have at least one of externalId, contactId, or email.

Channel fields

Field	Type	Required	Description
channel	string	Yes	email, sms, or whatsapp
providerId	UUID	Yes	Channel provider ID (must belong to your org)
templateId	UUID	Yes	Message template ID (must match the channel)
priority	number	No	1–10 (default: 1)
fromEmail	string	No	Sender email override (email channel only)
fromName	string	No	Sender name override
replyToEmail	string	No	Reply-to email override
fallbackDelayMinutes	number	No	Minutes before trying the next channel (multi mode)

Contact Resolution Order

Contacts are resolved in this priority order:

1. contactId — direct lookup by ID; returns 404 if not found
2. externalId — upsert: creates a new contact if not found, updates if found (merges embeddedData)
3. email — lookup by email within the org; creates if not found

Response

{
  "distributionId": "0195e3a1-0000-7000-8000-000000000010",
  "mailingListId": "0195e3a1-0000-7000-8000-000000000011",
  "recipientCount": 1,
  "personalLinks": [
    {
      "externalId": "PAT-12345",
      "contactId": "0195e3a1-0000-7000-8000-000000000002",
      "email": "john.doe@example.com",
      "personalLinkCode": "aBcDeFgH"
    }
  ],
  "status": "sending"
}

Field	Type	Description
distributionId	UUID	The created distribution ID
mailingListId	UUID	The auto-created mailing list ID
recipientCount	number	Number of eligible recipients
personalLinks	array	Per-recipient personal link codes
status	string	sending (immediate) or scheduled

The personalLinkCode can be used to construct a direct survey URL: https://your-domain/p/{personalLinkCode}

Settings

{
  "settings": {
    "excludeOptedOut": true,
    "respectFrequencyRules": true,
    "excludeRecentlyContacted": false,
    "recentContactDays": 30
  }
}

Setting	Default	Description
excludeOptedOut	true	Skip contacts who have opted out
respectFrequencyRules	true	Honor minimum days between contacts
excludeRecentlyContacted	false	Skip contacts contacted within recentContactDays
recentContactDays	—	Number of days to consider “recent” (1–365)