Importing Members via API

If you already have a customer database (CRM, e-commerce platform, internal system), you can programmatically import members using the Vora API. This is ideal for:

• Syncing your existing customer list into Vora

• Automating member onboarding from your CRM or Shopify store

• Importing large datasets without using the UI

API Endpoint

POST /api/v1/governance/{org_slug}/whitelist/import/

Authentication

Use your organization's API key (found in Settings > Advanced > API Key):

Authorization: Bearer YOUR_API_KEY

Request Format

Send a multipart/form-data request with a CSV file attached as file:

curl -X POST "https://api.cathedral.technology/api/v1/governance/your-org-slug/whitelist/import/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]"

CSV Format

The CSV file must contain a phone column. All other columns are optional:

Column	Required	Description
phone	Yes	Phone number with country code (e.g., [phone])
name or display_name	No	Member's display name
customer_id or crm_id	No	Your external CRM/customer ID for reconciliation
group	No	Group assignment

Example CSV with customer IDs:

phone,name,customer_id,group
[phone],John Doe,CRM-001,VIP
[phone],Jane Smith,CRM-002,Standard
[phone],Bob Johnson,SHOP-1234,VIP
[phone],Hans Mueller,HUB-5678,Standard

The customer_id field is especially useful if you need to cross-reference Vora members with your existing CRM, Shopify, HubSpot, or any other external system. It is stored alongside the member record and appears in:

• The Members list table

• API responses when querying users

• Webhook payloads for vote events

Alternative Column Names

The API accepts multiple common column name formats:

• Phone: phone, phone_number, mobile, Phone, Phone Number

• Name: name, display_name, Name

• Customer ID: customer_id, crm_id, Customer ID, CRM ID

Response

{
  "success": true,
  "added": 45,
  "skipped": 3,
  "errors": ["Row 12: Invalid phone format (+abc)"],
  "total_errors": 1
}

• added — Number of new members successfully created

• skipped — Members already in your whitelist (duplicates are detected automatically)

• errors — First 10 error messages (if any rows failed validation)

• total_errors — Total number of rows that had errors

Prerequisites

1. Data Processing Agreement (DPA) — You must accept the DPA in Settings before importing voter data (GDPR compliance requirement)

2. Plan quota — Your subscription plan determines the maximum number of members. If you hit the limit during import, remaining rows are skipped and a warning is returned

Example: Python Script for Bulk Import

import requests

API_KEY = "your-api-key"
ORG_SLUG = "your-org-slug"

url = f"https://api.cathedral.technology/api/v1/governance/{ORG_SLUG}/whitelist/import/"
headers = {"Authorization": f"Bearer {API_KEY}"}

with open("members.csv", "rb") as f:
    response = requests.post(url, headers=headers, files={"file": f})

result = response.json()
print(f"Added: {result['added']}, Skipped: {result['skipped']}, Errors: {result['total_errors']}")