Beginner15 minutes

Add Contacts

Learn how to implement contact management with import, export, and synchronization features using Origin Auth.

Prerequisites

An Origin Auth account with an active tenant
API credentials (tenant ID and API key)
Basic familiarity with REST APIs

Create a Contact

Add a contact to your tenant's directory.

Each contact is stored securely in your tenant's isolated namespace. Contact data is automatically encrypted at rest.

curl -X POST https://auth.origin-auth.io/v1.0/contacts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane.doe@example.com",
    "phone": "+1-555-0123",
    "metadata": {
      "source": "website-form",
      "company": "Example Corp"
    }
  }'

Search and Filter Contacts

Query your contact directory with filters and pagination.

The Contacts API supports advanced search, filtering, and pagination to help you manage large directories.

# Search contacts by name or email
curl -X GET "https://auth.origin-auth.io/v1.0/contacts?search=jane&page=1&limit=20" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Filter by metadata
curl -X GET "https://auth.origin-auth.io/v1.0/contacts?filter[source]=website-form" \
  -H "Authorization: Bearer YOUR_TOKEN"

Import Contacts in Bulk

Import multiple contacts at once from CSV or JSON.

Use the bulk import endpoint to upload contacts from your existing systems. The API validates each entry and reports errors per row.

curl -X POST https://auth.origin-auth.io/v1.0/contacts/import \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      {
        "firstName": "Alice",
        "lastName": "Smith",
        "email": "alice@example.com"
      },
      {
        "firstName": "Bob",
        "lastName": "Johnson",
        "email": "bob@example.com"
      }
    ],
    "options": {
      "skipDuplicates": true,
      "notifyOnComplete": true
    }
  }'

Export Contacts

Export your contact directory for backup or integration.

Export contacts in CSV or JSON format. Large exports are processed asynchronously with a downloadable link.

# Request an export
curl -X POST https://auth.origin-auth.io/v1.0/contacts/export \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "csv",
    "fields": ["firstName", "lastName", "email", "phone"]
  }'

# Check export status
curl -X GET "https://auth.origin-auth.io/v1.0/contacts/exports/EXPORT_ID" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Download when ready
curl -X GET "https://auth.origin-auth.io/v1.0/contacts/exports/EXPORT_ID/download" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o contacts-export.csv

Enable SCIM Directory Sync

Automatically sync contacts from your identity provider using SCIM 2.0.

Origin Auth supports SCIM 2.0 for automated user provisioning. Connect your identity provider to keep contacts in sync.

# Get your SCIM endpoint URL
curl -X GET https://auth.origin-auth.io/v1.0/scim/configuration \
  -H "Authorization: Bearer YOUR_TOKEN"

# Response includes:
# {
#   "endpoint": "https://auth.origin-auth.io/scim/v2",
#   "token": "scim-bearer-token",
#   "supported": ["User", "Group"]
# }

# Configure SCIM in your IdP (Okta, Azure AD, etc.)
# Use the endpoint and token above

What You've Learned

Creating and managing contacts via the API
Searching and filtering your contact directory
Bulk importing contacts from CSV or JSON
Exporting contacts for backup or migration
Setting up SCIM 2.0 for automatic directory sync

Next Steps

Continue learning with these related tutorials:

Build a Membership Site

User registration and RBAC

Set Up SSO

Single sign-on configuration