Bloque SDK
  • 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

      StatusDescription
      awaiting_compliance_verificationPending compliance verification
      activeOrganization is active
      suspendedOrganization is suspended
      closedOrganization is 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