Organization

An Organization represents a company or other legal entity within your application. Organizations store legal and business information and can own multiple sub-resources including addresses, contact methods, preferences, and bank accounts. People can be linked to organizations through the organization-person relationship.

Sample Object

{
  "id": "org_abc123def456",
  "name": "Acme Corp",
  "legal_name": "Acme Corporation Inc.",
  "active": true,
  "registration_number": "US123456789",
  "legal_form": "LLC",
  "vat_number": "VAT-US123456",
  "tax_id": "TAX-987654",
  "founded_date": "2010-05-15T00:00:00Z",
  "type": "technology",
  "industry": "software",
  "currency": "USD",
  "size": "MEDIUM",
  "primary_address_id": "adr_xyz789uvw012",
  "primary_contact_method_id": "cnt_mno345pqr678",
  "primary_bank_account_id": "bnk_678stu901vwx"
}

Fields

Field	Type	Description
`id`	`string`	Unique identifier for the organization. Auto-generated on create.
`name`	`string`	Common name of the organization. Minimum 2 characters.
`legal_name`	`string`	Registered legal name of the organization. Minimum 2 characters.
`active`	`boolean`	Whether the organization is active.
`registration_number`	`string`	Official business registration number.
`legal_form`	`string`	Legal structure such as LLC, Corporation, or Partnership.
`vat_number`	`string`	Value-added tax identification number.
`tax_id`	`string`	Taxpayer identification number.
`founded_date`	`datetime`	Date the organization was founded. ISO 8601 format.
`type`	`string`	Business type or category.
`industry`	`string`	Industry classification.
`currency`	`string`	Default currency for the organization. ISO 4217 format.
`size`	`enum`	Employee count range. One of `MICRO`, `SMALL`, `MEDIUM`, `LARGE`.
`primary_address_id`	`nullable string`	ID of the primary address. Set automatically when an address is marked as primary.
`primary_contact_method_id`	`nullable string`	ID of the primary contact method. Set automatically when a contact method is marked as primary.
`primary_bank_account_id`	`nullable string`	ID of the primary bank account. Set automatically when a bank account is marked as primary.

Actions

Creating an organization

Creates a new organization record. The organization is created in an active state by default.

obx app identity:organizations init
obx app identity:organizations push init

POST /api/v1/identity/organizations

{
  "name": "Acme Corp",
  "legal_name": "Acme Corporation Inc.",
  "size": "MEDIUM",
  "currency": "USD"
}

Successful response

{
  "id": "org_abc123def456",
  "name": "Acme Corp",
  "legal_name": "Acme Corporation Inc.",
  "active": true,
  "registration_number": "",
  "legal_form": "",
  "vat_number": "",
  "tax_id": "",
  "founded_date": null,
  "type": "",
  "industry": "",
  "currency": "USD",
  "size": "MEDIUM",
  "primary_address_id": null,
  "primary_contact_method_id": null,
  "primary_bank_account_id": null
}

Onboard an organization

Creates an organization together with addresses, contact methods, preferences, and bank accounts in a single request. The first item in each sub-resource collection is automatically set as the primary.

obx app identity:organizations init
obx app identity:organizations push init

const org = await oblax.identity.organization.onboard({
  name: "Acme Corp",
  legal_name: "Acme Corporation Inc.",
  size: "MEDIUM",
  currency: "USD",
  addresses: [
    {
      label: "HQ",
      country: "US",
      city: "San Francisco",
      zipcode: "94105",
      address: "Market Street",
      address_number: "123",
      longitude: -122.39,
      latitude: 37.79,
    },
  ],
  contact_methods: [
    {
      contact_type: "EMAIL",
      contact_kind: "BUSINESS",
      value: "contact@acme.com",
    },
  ],
  preferences: [
    {
      key: "timezone",
      value: "America/Los_Angeles",
      value_type: "STRING",
    },
  ],
  bank_accounts: [
    {
      account_number: "1234567890",
      bic: "BOFAUS3N",
      iban: "US12345678901234567890",
      currency: "USD",
    },
  ],
});

POST /api/v1/identity/organizations:onboard

{
  "name": "Acme Corp",
  "legal_name": "Acme Corporation Inc.",
  "size": "MEDIUM",
  "currency": "USD",
  "addresses": [
    {
      "label": "HQ",
      "country": "US",
      "city": "San Francisco",
      "zipcode": "94105",
      "address": "Market Street",
      "address_number": "123",
      "longitude": -122.39,
      "latitude": 37.79
    }
  ],
  "contact_methods": [
    {
      "contact_type": "EMAIL",
      "contact_kind": "BUSINESS",
      "value": "contact@acme.com"
    }
  ],
  "preferences": [
    {
      "key": "timezone",
      "value": "America/Los_Angeles",
      "value_type": "STRING"
    }
  ],
  "bank_accounts": [
    {
      "account_number": "1234567890",
      "bic": "BOFAUS3N",
      "iban": "US12345678901234567890",
      "currency": "USD"
    }
  ]
}

Successful response

{
  "id": "org_abc123def456",
  "name": "Acme Corp",
  "legal_name": "Acme Corporation Inc.",
  "active": true,
  "currency": "USD",
  "size": "MEDIUM",
  "primary_address_id": "adr_xyz789uvw012",
  "primary_contact_method_id": "cnt_mno345pqr678",
  "primary_bank_account_id": "bnk_678stu901vwx"
}

Listing all organizations

Returns all organizations. Each organization object includes core fields but not sub-resources.

obx app identity:organizations list

GET /api/v1/identity/organizations

Successful response

[
  {
    "id": "org_abc123def456",
    "name": "Acme Corp",
    "legal_name": "Acme Corporation Inc.",
    "active": true,
    "currency": "USD",
    "size": "MEDIUM",
    "primary_address_id": null,
    "primary_contact_method_id": null,
    "primary_bank_account_id": null
  }
]

Getting an organization

Returns the full organization object for the given ID. Sub-resources are not included. Use the full details action to include addresses, contact methods, preferences, and bank accounts.

obx app identity:organizations pull org_abc123def456

GET /api/v1/identity/organizations/org_abc123def456

Successful response

{
  "id": "org_abc123def456",
  "name": "Acme Corp",
  "legal_name": "Acme Corporation Inc.",
  "active": true,
  "currency": "USD",
  "size": "MEDIUM",
  "primary_address_id": null,
  "primary_contact_method_id": null,
  "primary_bank_account_id": null
}

Getting an organizations full details

Returns the organization object with all associated addresses, contact methods, preferences, and bank accounts embedded.

obx app identity:organizations pull org_abc123def456 --full

GET /api/v1/identity/organizations/org_abc123def456:full

Successful response

{
  "id": "org_abc123def456",
  "name": "Acme Corp",
  "legal_name": "Acme Corporation Inc.",
  "active": true,
  "currency": "USD",
  "size": "MEDIUM",
  "primary_address_id": "adr_xyz789uvw012",
  "primary_contact_method_id": "cnt_mno345pqr678",
  "primary_bank_account_id": "bnk_678stu901vwx",
  "addresses": [
    {
      "id": "adr_xyz789uvw012",
      "label": "HQ",
      "country": "US",
      "city": "San Francisco",
      "zipcode": "94105",
      "address": "Market Street",
      "address_number": "123",
      "longitude": -122.39,
      "latitude": 37.79
    }
  ],
  "contact_methods": [
    {
      "id": "cnt_mno345pqr678",
      "contact_type": "EMAIL",
      "contact_kind": "BUSINESS",
      "value": "contact@acme.com"
    }
  ],
  "preferences": [
    {
      "id": "pre_stu901vwx234",
      "key": "timezone",
      "value": "America/Los_Angeles",
      "value_type": "STRING"
    }
  ],
  "bank_accounts": [
    {
      "id": "bnk_678stu901vwx",
      "account_number": "1234567890",
      "bic": "BOFAUS3N",
      "iban": "US12345678901234567890",
      "currency": "USD"
    }
  ]
}

Updating an organization

Updates the core fields of an organization. Only the provided fields are modified.

obx app identity:organizations push org_abc123def456

Deleting an organization

Removes an organization and all associated addresses, contact methods, preferences, and bank accounts.

obx app identity:organizations delete org_abc123def456

Person Address