Documentation Index Fetch the complete documentation index at: https://embed.usesticker.com/llms.txt
Use this file to discover all available pages before exploring further.
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.
Sticker’s data model assumes a many-to-one relationship from profiles to organizations:
An organization represents the customer business, company, practice, store, school, or legal entity.
A profile represents an employee or user inside that organization.
Multiple profiles can belong to the same organization.
Different businesses must not share the same internalOrgId.
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
internalOrgId is the unique key Sticker uses to identify a business organization for your partner account. Reusing one generic internalOrgId across multiple unrelated companies will group those companies into the same Sticker 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 unique internal identifier for this business organization. Use the same value only for users who belong to the same business. Use a different value for every distinct customer business.
Display name for the organization.
Your internal identifier for this user or employee. Each user in the same organization should have a unique internalUserId.
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 Organization Identity: Do not reuse one shared internalOrgId for multiple customer businesses. For example, if you have 50 stores, cleaning companies, practices, or schools, you should send 50 distinct internalOrgId values. Employees from the same business should share that business’s internalOrgId and have distinct internalUserId values.
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.
