Skip to content
/
Make a List

Make a List

Request

Make a new List, optionally with organizations on it. Send an Idempotency-Key so a retry makes one List, not two. Use this when someone asks to save a set of organizations. Answers 201 with the List. The same Idempotency-Key and body again answers 200 with the same id; another body under that key is 409 idempotency_conflict. Rows added here read "by API key" in the app.

Security
bearerKey
Headers
Idempotency-Keystring, [ 1 .. 128 ] characters

1 to 128 characters. A retry with the same key and body returns the first result; the same key with another body is 409.

Bodyapplication/jsonrequired
namestring, [ 1 .. 200 ] charactersrequired
purposestring
Default:"general"
Enum:"general""targets""audience"
rowsArray of integers, [ 1 .. 10000 ] items
curl -i -X POST \
  https://docs.societyhealth.co/_mock/docs/openapi/api/v1/lists \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Virginia systems",
    "purpose": "targets",
    "rows": [
      41,
      57
    ]
  }'

Responses

A retry: the same Idempotency-Key and body as a 201 before it; the same id.

Bodyapplication/json
okanyrequired
Value:true
dataobject(PublicList)required
Response
{
  "ok": true,
  "data": {
    "id": "Lst8kQ2mZp4xV7nR1tYw",
    "url": "https://hrcledger.com/lists/items/Lst8kQ2mZp4xV7nR1tYw",
    "name": "Virginia systems",
    "purpose": "general",
    "archived": false,
    "revisionNo": 2,
    "updatedAt": "2026-10-16T14:02:11.000Z"
  }
}