Add campaign recipients

POST/campaigns/{campaignId}/recipients

Adds up to 10,000 patients to a campaign that isn’t completed or stopped. Unknown patient IDs, and patients already on the campaign, are skipped and listed in skipped. Recipients added to a running campaign are sent after the ones already waiting.

Credentials: API key or an org admin’s OAuth token
Scope: messages.write
Idempotent: With Idempotency-Key

Path parameters

campaignIdUUIDRequired

ID of the campaign.

Headers

Idempotency-KeyUUIDRequired

A UUID you generate for each write. Retrying with the same key returns the original result for 24 hours. Reusing a key with a different method, path, or body returns 409.

Body parameters

patient_idsarray of UUIDRequired

Up to 10,000 patient IDs.

Returns

Returns 200 OK with changed, the number of patients added, and skipped, each patient left unchanged with its reason.

Errors

Failed requests return application/problem+json problem details. The errors specific to this endpoint:

Status	Code	Meaning
400	`invalid_request`	The request is malformed, such as invalid JSON.
401	`invalid_token`	The API key or access token is missing, expired, or revoked.
403	`insufficient_scope`	The credential doesn’t have the scope this endpoint needs.
404	`not_found`	The resource doesn’t exist, or isn’t visible to this credential.
409	`idempotency_key_reused`	The Idempotency-Key was already used with a different request.
409	`idempotency_request_in_progress`	A request with this Idempotency-Key is still running. Retry shortly.
409	`campaign_not_editable`	The campaign is completed or stopped.
422	`validation_failed`	A field failed validation. See `field_errors`.
429	`rate_limited`	Too many requests. Retry after `Retry-After` seconds.

cURL

Request


curl -X POST "https://api.bloomtext.com/v1/campaigns/c4a7e2d1-9b3f-4e6a-8d2c-1f0e9b8a7c65/recipients" \
  -H "Authorization: Bearer $BLOOMTEXT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"patient_ids":["5a1c9e2b-7d44-4f1a-9c3e-2b8d6f0a1e77","9e0d3f7a-2c1b-4e8d-a5f6-7b3c2d1e0f98"]}'

JavaScript

Request


const response = await fetch('https://api.bloomtext.com/v1/campaigns/c4a7e2d1-9b3f-4e6a-8d2c-1f0e9b8a7c65/recipients', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BLOOMTEXT_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"patient_ids":["5a1c9e2b-7d44-4f1a-9c3e-2b8d6f0a1e77","9e0d3f7a-2c1b-4e8d-a5f6-7b3c2d1e0f98"]}),
})
 
if (!response.ok) throw new Error(`BloomText API error: ${response.status}`)
const data = await response.json()

Python

Request


import os
import uuid
 
import requests
 
response = requests.post(
    "https://api.bloomtext.com/v1/campaigns/c4a7e2d1-9b3f-4e6a-8d2c-1f0e9b8a7c65/recipients",
    headers={
        "Authorization": f"Bearer {os.environ['BLOOMTEXT_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"patient_ids":["5a1c9e2b-7d44-4f1a-9c3e-2b8d6f0a1e77","9e0d3f7a-2c1b-4e8d-a5f6-7b3c2d1e0f98"]},
)
response.raise_for_status()
data = response.json()

Go

Request


package main
 
import (
	"bytes"
	"fmt"
	"io"
	"net/http"
	"os"
 
	"github.com/google/uuid"
)
 
func main() {
	body := bytes.NewBufferString(`{"patient_ids":["5a1c9e2b-7d44-4f1a-9c3e-2b8d6f0a1e77","9e0d3f7a-2c1b-4e8d-a5f6-7b3c2d1e0f98"]}`)
	req, err := http.NewRequest("POST", "https://api.bloomtext.com/v1/campaigns/c4a7e2d1-9b3f-4e6a-8d2c-1f0e9b8a7c65/recipients", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("BLOOMTEXT_API_KEY"))
	req.Header.Set("Idempotency-Key", uuid.NewString())
	req.Header.Set("Content-Type", "application/json")
 
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
 
	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(out))
}

Ruby

Request


require "net/http"
require "json"
require "securerandom"
 
uri = URI("https://api.bloomtext.com/v1/campaigns/c4a7e2d1-9b3f-4e6a-8d2c-1f0e9b8a7c65/recipients")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("BLOOMTEXT_API_KEY")}"
request["Idempotency-Key"] = SecureRandom.uuid
request["Content-Type"] = "application/json"
request.body = { patient_ids: ["5a1c9e2b-7d44-4f1a-9c3e-2b8d6f0a1e77","9e0d3f7a-2c1b-4e8d-a5f6-7b3c2d1e0f98"] }.to_json
 
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end
data = JSON.parse(response.body)

Response · 200 OK


{
  "changed": 2,
  "skipped": []
}