Organization Setup

Overview

The Organization Setup endpoint is called once when a customer enables the supplies module in your platform. This endpoint creates the organization profile, shipping addresses, and user accounts in Sticker’s system.

When to Call This Endpoint

User Enables Feature

A customer clicks “Enable Supplies” or similar in your platform

Validate Permissions

Verify the user has admin rights to enable organization-wide features

Collect Required Data

Gather organization details, addresses, and user list

Call Setup Endpoint

Send data to Sticker to provision the organization

Store Integration ID

Save the returned profile ID for future API calls

API Endpoint

POST /api/partner/organization-setup

Base URL: https://api.sticker.com (production) or https://sandbox.api.sticker.com (sandbox)

Authentication

Include your Partner API Key in the Authorization header:

Authorization: Bearer sk_live_your_api_key_here

Request Format

OAuth Flow (Recommended)

If you have an OAuth integration with Sticker:

{
  "grant_type": "authorization_code",
  "code": "oauth_authorization_code",
  "partner_org_id": "your_internal_org_id"
}

Sticker will automatically fetch organization and user data using the access token.

Manual Data Push

If you don’t use OAuth, send the complete organization structure:

{
  "organization": {
    "name": "Acme Medical Practice",
    "email": "admin@acmemedical.com",
    "phone": "+1-555-123-4567",
    "addresses": [
      {
        "line1": "123 Medical Plaza",
        "line2": "Suite 200",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94102",
        "country": "US",
        "is_primary": true
      },
      {
        "line1": "456 Health Center",
        "city": "Oakland",
        "state": "CA",
        "zip": "94607",
        "country": "US",
        "is_primary": false
      }
    ]
  },
  "users": [
    {
      "email": "dr.smith@acmemedical.com",
      "first_name": "John",
      "last_name": "Smith",
      "role": "admin"
    },
    {
      "email": "dr.jones@acmemedical.com",
      "first_name": "Sarah",
      "last_name": "Jones",
      "role": "member"
    }
  ],
  "partner_org_id": "your_internal_org_id"
}

Request Parameters

Organization Object

organization.name

string

required

The legal or display name of the organization

organization.email

string

required

Primary contact email for the organization (must be valid email format)

organization.phone

string

Primary phone number (E.164 format recommended: +1-555-123-4567)

organization.addresses

array

required

Array of shipping/billing addresses (at least one required)

Address Object

addresses[].line1

string

required

Street address, P.O. box, company name

addresses[].line2

string

Apartment, suite, unit, building, floor, etc.

addresses[].city

string

required

City, district, suburb, town, or village

addresses[].state

string

required

State, province, or region (2-letter abbreviation for US/CA)

addresses[].zip

string

required

ZIP or postal code

addresses[].country

string

required

Two-letter country code (ISO 3166-1 alpha-2)

addresses[].is_primary

boolean

required

Whether this is the default shipping address

Users Array

users

array

required

List of users to create in the organization (at least one admin required)

users[].email

string

required

User’s email address (unique identifier)

users[].first_name

string

required

User’s first name

users[].last_name

string

required

User’s last name

users[].role

string

User role: admin or member (defaults to member)

Partner Org ID

partner_org_id

string

required

Your internal identifier for this organization. Used to link future handshake requests.

Response Format

Success Response (201 Created)

{
  "success": true,
  "action": "created",
  "profile": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "organization_name": "Acme Medical Practice",
    "partner_org_id": "your_internal_org_id",
    "email": "admin@acmemedical.com",
    "created_at": "2024-12-11T10:30:00Z"
  },
  "users_created": 2,
  "addresses_created": 2
}

success

boolean

Whether the operation succeeded

action

string

Action taken: created or updated (if organization already existed)

profile.id

string

Sticker’s unique identifier for this organization profile

profile.partner_org_id

string

Your internal org ID (echoed back for verification)

users_created

number

Number of user accounts created

addresses_created

number

Number of addresses added to the profile

Error Responses

400 Bad Request

{
  "error": "Missing required field: organization.email",
  "code": "INVALID_REQUEST"
}

Common causes:

Missing required fields
Invalid email format
Invalid country/state codes
No primary address specified

401 Unauthorized

{
  "error": "Invalid API key",
  "code": "UNAUTHORIZED"
}

Solution: Verify your API key is correct and active

409 Conflict

{
  "error": "Organization already exists with partner_org_id: your_internal_org_id",
  "code": "DUPLICATE_ORGANIZATION",
  "existing_profile_id": "550e8400-e29b-41d4-a716-446655440000"
}

Solution: Use the existing profile ID for handshake requests, or call with update: true to modify existing organization

500 Internal Server Error

{
  "error": "Failed to create organization",
  "code": "INTERNAL_ERROR",
  "details": "Database connection timeout"
}

Solution: Retry with exponential backoff, contact support if persistent

Code Examples

const crypto = require('crypto');

async function setupOrganization(orgData, users) {
  const requestBody = {
    organization: {
      name: orgData.name,
      email: orgData.email,
      phone: orgData.phone,
      addresses: orgData.addresses.map(addr => ({
        line1: addr.street,
        line2: addr.suite,
        city: addr.city,
        state: addr.state,
        zip: addr.zipCode,
        country: addr.country || 'US',
        is_primary: addr.isPrimary || false
      }))
    },
    users: users.map(user => ({
      email: user.email,
      first_name: user.firstName,
      last_name: user.lastName,
      role: user.isAdmin ? 'admin' : 'member'
    })),
    partner_org_id: orgData.id
  };

  const response = await fetch('https://api.sticker.com/api/partner/organization-setup', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.STICKER_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(requestBody)
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Setup failed: ${error.error}`);
  }

  const result = await response.json();
  
  // Store the profile ID in your database
  await saveProfileId(orgData.id, result.profile.id);
  
  return result;
}

Updating Organizations

To update an existing organization, send the same request with updated data. Sticker will:

Match based on partner_org_id
Update changed fields
Add new addresses/users
Preserve existing data not included in the request

{
  "organization": {
    "name": "Acme Medical Practice (Updated Name)",
    "email": "newemail@acmemedical.com",
    "addresses": [
      {
        "line1": "789 New Location",
        "city": "San Jose",
        "state": "CA",
        "zip": "95110",
        "country": "US",
        "is_primary": true
      }
    ]
  },
  "users": [
    {
      "email": "new.doctor@acmemedical.com",
      "first_name": "Emily",
      "last_name": "Brown",
      "role": "member"
    }
  ],
  "partner_org_id": "your_internal_org_id",
  "update": true
}

Updates are additive. Existing users and addresses are not deleted unless explicitly specified.

Best Practices

Data Validation

Validate email addresses before sending
Ensure phone numbers are in E.164 format
Verify state/country codes match ISO standards
Confirm at least one primary address exists

Error Handling

Implement retry logic with exponential backoff
Log all API responses for debugging
Display user-friendly error messages
Handle partial failures gracefully

Data Storage

Store the returned profile.id in your database
Link it to your internal organization ID
Keep track of integration status
Log setup timestamp for audit trails

User Experience

Show progress indicators during setup
Confirm successful enablement
Provide clear next steps
Offer support contact if setup fails

Testing

Test your organization setup in the sandbox environment:

# Sandbox API
https://sandbox.api.sticker.com/api/partner/organization-setup

# Use test data
{
  "organization": {
    "name": "Test Medical Practice",
    "email": "test@example.com",
    ...
  }
}

Sandbox data is automatically cleared every 30 days. Use it freely for testing without affecting production.

Get Started

Overview

When to Call This Endpoint

API Endpoint

Authentication

Request Format

OAuth Flow (Recommended)

Manual Data Push

Request Parameters

Organization Object

Address Object

Users Array

Partner Org ID

Response Format

Success Response (201 Created)

Error Responses

Code Examples

Updating Organizations

Best Practices

Testing

Next Steps

User Handshake

API Reference

Get Started

​Overview

​When to Call This Endpoint

​API Endpoint

​Authentication

​Request Format

​OAuth Flow (Recommended)

​Manual Data Push

​Request Parameters

​Organization Object

​Address Object

​Users Array

​Partner Org ID

​Response Format

​Success Response (201 Created)

​Error Responses

​Code Examples

​Updating Organizations

​Best Practices

​Testing

​Next Steps

User Handshake

API Reference

Overview

When to Call This Endpoint

API Endpoint

Authentication

Request Format

OAuth Flow (Recommended)

Manual Data Push

Request Parameters

Organization Object

Address Object

Users Array

Partner Org ID

Response Format

Success Response (201 Created)

Error Responses

Code Examples

Updating Organizations

Best Practices

Testing

Next Steps