🚧 Bloque documentation is under development
close
Bloque Docs
  • English

      • Organizations

      Learn how to create and manage organizations using the Bloque SDK.

      Overview

      Organizations are the foundation of the Bloque platform. They can be either businesses or individuals and contain all the necessary profile and compliance information.

      Creating an Organization

      Business Organization

      import { SDK } from '@bloque/sdk';
import type { CreateOrgParams } from '@bloque/sdk/orgs';

const bloque = new SDK({
  origin: 'your-origin',
  auth: {
    type: 'apiKey',
    apiKey: process.env.BLOQUE_API_KEY!,
  },
  mode: 'production',
});

const params: CreateOrgParams = {
  org_type: 'business',
  profile: {
    legal_name: 'Acme Corporation',
    tax_id: '123456789',
    incorporation_date: '2020-01-01',
    business_type: 'llc',
    incorporation_country_code: 'US',
    incorporation_state: 'CA',
    address_line1: '123 Main St',
    postal_code: '94103',
    city: 'San Francisco',
  },
  metadata: {
    source: 'web_app',
    campaign: 'q1_2024',
  },
};

const organization = await bloque.orgs.create(params);

      Individual Organization

      const params: CreateOrgParams = {
  org_type: 'individual',
  profile: {
    legal_name: 'John Doe',
    tax_id: '123-45-6789',
    incorporation_date: '1990-05-20',
    business_type: 'sole_proprietorship',
    incorporation_country_code: 'US',
    address_line1: '456 Oak Ave',
    postal_code: '10001',
    city: 'New York',
  },
};

const organization = await bloque.orgs.create(params);

      Parameters

      CreateOrgParams

      FieldTypeRequiredDescription
      org_type'business' | 'individual'YesType of organization
      profileOrgProfileYesOrganization profile details
      metadataRecord<string, unknown>NoCustom metadata

      OrgProfile

      FieldTypeRequiredDescription
      legal_namestringYesLegal name of the organization
      tax_idstringYesTax ID number
      incorporation_datestringYesDate of incorporation (YYYY-MM-DD)
      business_typestringYesType of business (e.g., 'llc', 'corporation')
      incorporation_country_codestringYesCountry code (ISO 3166-1 alpha-2)
      incorporation_statestringNoState/province
      address_line1stringYesPrimary address line
      address_line2stringNoSecondary address line
      postal_codestringYesPostal/ZIP code
      citystringYesCity
      logo_urlstringNoLogo URL
      placesPlace[]NoAdditional locations

      Response

      Organization

      interface Organization {
  urn: string;                           // Unique resource name
  org_type: 'business' | 'individual';   // Organization type
  profile: OrgProfile;                   // Organization profile
  metadata?: Record<string, unknown>;    // Custom metadata
  status: OrgStatus;                     // Organization status
}

      Organization Status

      StatusDescriptionCan Transition To
      awaiting_compliance_verificationPending compliance verificationactive, suspended, closed
      activeOrganization is active and can operatesuspended, closed
      suspendedOrganization is temporarily suspended for compliance violationactive, closed
      closedOrganization is permanently closed-
      stateDiagram-v2
    [*] --> awaiting_compliance_verification
    awaiting_compliance_verification --> active
    awaiting_compliance_verification --> suspended
    awaiting_compliance_verification --> closed
    active --> suspended
    active --> closed
    suspended --> active
    suspended --> closed
    closed --> [*]

      Multi-location Organizations

      For organizations with multiple locations, use the places field:

      const params: CreateOrgParams = {
  org_type: 'business',
  profile: {
    legal_name: 'Global Tech Inc',
    tax_id: '98-7654321',
    incorporation_date: '2018-03-10',
    business_type: 'corporation',
    incorporation_country_code: 'US',
    incorporation_state: 'DE',
    address_line1: '789 Corporate Blvd',
    postal_code: '19801',
    city: 'Wilmington',
    places: [
      {
        country_code: 'US',
        state: 'CA',
        address_line1: '100 Silicon Valley Dr',
        postal_code: '94025',
        city: 'Menlo Park',
        is_primary: true,
      },
      {
        country_code: 'US',
        state: 'NY',
        address_line1: '250 Broadway',
        postal_code: '10007',
        city: 'New York',
        is_primary: false,
      },
    ],
  },
};

      Custom Metadata

      Add custom fields to track additional information:

      const params: CreateOrgParams = {
  org_type: 'business',
  profile: {
    // ... profile fields
  },
  metadata: {
    source: 'api',
    customer_id: 'cust_123',
    plan: 'enterprise',
    referral_code: 'REF2024',
  },
};

      Best Practices

      1. Validate Data: Ensure all required fields are present before calling the API
      2. Handle Errors: Always use try-catch blocks
      3. Store URNs: Save the organization URN for future operations
      4. Use Metadata: Track additional context using metadata
      5. Test in Sandbox: Always test with mode: 'sandbox' first

      Next Steps