Endpoint POST /v1/organizations/setup
Base URL: https://api.usesticker.comStaging/Sandbox URL: https://staging.api.usesticker.comDescription Sets up an organization with a user profile and shipping locations in Sticker. This endpoint handles both creating new organizations and adding new users to existing organizations.
Behavior:
If organization with internalOrgId does not exist : Creates organization, user profile, and shipping locations
If organization already exists : Creates a new user profile linked to the existing organization
Authentication Requires Partner API key with organization:write scope.
Authorization: Bearer sk_live_your_api_key_here
Request Body { "internalOrgId" : "org-12345" , "organizationName" : "Acme Medical Practice" , "internalUserId" : "user-789" , "user" : { "firstName" : "Jane" , "lastName" : "Smith" , "email" : "jane@acmemedical.com" , "phoneNumber" : "+1-555-0100" }, "userAddress" : { "line1" : "456 User Street" , "line2" : "Apt 2B" , "city" : "San Francisco" , "province" : "California" , "postalCode" : "94102" , "country" : "United States" }, "shippingLocations" : [ { "internalShippingLocationId" : "loc-001" , "name" : "Main Office" , "nickname" : "HQ" , "address" : { "line1" : "123 Medical Plaza" , "line2" : "Suite 200" , "city" : "San Francisco" , "province" : "CA" , "postalCode" : "94102" , "country" : "United States" }, "contact" : { "name" : "Office Manager" , "phone" : "+1-555-0101" , "email" : "office@acmemedical.com" }, "isDefault" : true , "deliveryInstructions" : "Ring bell, leave at front desk" } ], "billingAddress" : { "line1" : "123 Medical Plaza" , "line2" : "Suite 200" , "city" : "San Francisco" , "province" : "California" , "postalCode" : "94102" , "country" : "United States" }, "organizationEmail" : "billing@acmemedical.com" , "organizationPhone" : "+1-555-0100" }
Request Parameters Required Fields Your internal identifier for this organization. Used to link Sticker data back to your system.
Display name for the organization.
Your internal identifier for this user. Used to link the user back to your system.
User profile information.
User’s email address. Must be a valid email format.
Optional Fields User’s personal address (different from organization shipping locations).
Array of shipping locations for the organization. Recommended for new organizations.
Organization’s billing address.
Organization’s primary contact email.
Organization’s primary phone number.
Address Object Used for userAddress, billingAddress, and shippingLocations[].address:
Street address line 2 (apartment, suite, etc.).
State/Province. Accepts full name (e.g., “California”) or abbreviation (e.g., “CA”).
Country. Defaults to “United States”. Currently only US is supported.
Shipping Location Object shippingLocations[].internalShippingLocationId
Your internal identifier for this shipping location.
Display name for the location (e.g., “Main Office”, “Warehouse”).
shippingLocations[].nickname
Short nickname for the location.
shippingLocations[].address
Address object (see above).
shippingLocations[].contact
Contact information for delivery.
shippingLocations[].contact.name
Contact person’s name.
shippingLocations[].contact.phone
Contact phone number.
shippingLocations[].contact.email
Contact email address.
shippingLocations[].isDefault
Whether this is the default shipping location. Defaults to false.
shippingLocations[].deliveryInstructions
Special instructions for delivery drivers.
Response Success Response (200 OK) { "success" : true , "data" : { "organization" : { "id" : "550e8400-e29b-41d4-a716-446655440000" , "name" : "Acme Medical Practice" , "internalOrgId" : "org-12345" , "stripeCustomerId" : "cus_xxxxxxxxxxxxx" }, "profile" : { "id" : "660f9500-f30c-52e5-b827-557766551111" , "partner" : "770a0600-g41d-63f6-c938-668877662222" , "organization" : "550e8400-e29b-41d4-a716-446655440000" , "internal_user_id" : "user-789" , "user" : "880b1700-h52e-74g7-d049-779988773333" , "first_name" : "Jane" , "last_name" : "Smith" , "email" : "jane@acmemedical.com" , "phone_number" : "+1-555-0100" , "created_at" : "2024-01-15T10:30:00.000Z" }, "shippingLocations" : [ { "id" : "990c2800-i63f-85h8-e150-880099884444" , "name" : "Main Office" , "nickname" : "HQ" , "internalShippingLocationId" : "loc-001" , "address" : { "line1" : "123 Medical Plaza" , "line2" : "Suite 200" , "city" : "San Francisco" , "province" : "California" , "postalCode" : "94102" , "country" : "United States" }, "isDefault" : true , "isActive" : true } ], "isNewOrganization" : true } }
Response Fields Whether the operation succeeded.
Sticker’s unique identifier for the organization (UUID).
data.organization.stripeCustomerId
Stripe customer ID for billing.
Sticker’s unique identifier for the user profile (UUID).
Supabase Auth user ID linked to this profile.
Array of shipping locations. For existing organizations, returns all existing locations.
true if a new organization was created, false if user was added to existing organization.
Error Responses
{ "error" : "Validation Error" , "message" : "Invalid request body" , "code" : "VALIDATION_ERROR" , "details" : [ { "code" : "invalid_string" , "message" : "Invalid email" , "path" : [ "user" , "email" ] } ] }
Common causes:
Missing required fields
Invalid email format
Invalid state/province (must be valid US state)
{ "error" : "Unauthorized" , "message" : "Invalid or missing API key" , "code" : "UNAUTHORIZED" }
Solution: Check your API key is correct and included in the Authorization header.
{ "error" : "Conflict" , "message" : "User already exists in this organization" , "code" : "USER_ALREADY_EXISTS" , "data" : { "profileId" : "660f9500-f30c-52e5-b827-557766551111" , "email" : "jane@acmemedical.com" } }
Solution: The user with this internalUserId already exists in this organization. Use the existing profile ID for handshake requests.
{ "error" : "Internal Server Error" , "message" : "Failed to setup organization" , "code" : "SETUP_ERROR" }
Solution: Retry with exponential backoff. Contact support if the error persists.Code Examples async function setupOrganization ( org , user , locations ) { const response = await fetch ( 'https://api.usesticker.com/v1/organizations/setup' , { method: 'POST' , headers: { 'Authorization' : `Bearer ${ process . env . STICKER_API_KEY } ` , 'Content-Type' : 'application/json' , }, body: JSON . stringify ({ internalOrgId: org . id , organizationName: org . name , internalUserId: user . id , user: { firstName: user . firstName , lastName: user . lastName , email: user . email , phoneNumber: user . phone }, shippingLocations: locations . map ( loc => ({ internalShippingLocationId: loc . id , name: loc . name , address: { line1: loc . address . line1 , line2: loc . address . line2 , city: loc . address . city , province: loc . address . state , postalCode: loc . address . zip }, isDefault: loc . isPrimary })) }) }); if ( ! response . ok ) { const error = await response . json (); throw new Error ( `Setup failed: ${ error . message } ` ); } return await response . json (); }
Notes State/Province Normalization: The API accepts both full state names (“California”) and abbreviations (“CA”). All values are normalized and stored as full state names internally.
Stripe Customer Creation: When creating a new organization, a Stripe customer is automatically created for billing. The stripeCustomerId is returned in the response for reference.
Adding Users to Existing Organizations: Call this endpoint again with the same internalOrgId but a different internalUserId to add additional users to an existing organization.
