Person

A Person represents an individual within your application. People store core identity information and can own multiple sub-resources including addresses, contact methods, preferences, and roles. A person can be linked to one or more organizations.

Sample Object

{
  "id": "ppl_abc123def456",
  "first_name": "Jane",
  "last_name": "Doe",
  "avatar": "https://example.com/avatars/jane.jpg",
  "active": true,
  "system_owned": false,
  "primary_address_id": "adr_xyz789uvw012",
  "primary_contact_method_id": "cnt_mno345pqr678"
}

Fields

Field	Type	Description
`id`	`string`	Unique identifier for the person. Auto-generated on create.
`first_name`	`string`	Given name of the person. Minimum 2 characters.
`last_name`	`string`	Family name of the person. Minimum 2 characters.
`avatar`	`string`	URL to the person’s avatar image. Optional.
`active`	`boolean`	Whether the person is active. Inactive people are excluded from most operations.
`system_owned`	`boolean`	Indicates whether this record is owned by the system. System-owned people cannot be deleted.
`primary_address_id`	`nullable string`	ID of the primary address for this person. Set automatically when an address is marked as primary.
`primary_contact_method_id`	`nullable string`	ID of the primary contact method for this person. Set automatically when a contact method is marked as primary.

Actions

Creating a person

Creates a new person record with the provided identity information. The person is created in an active state by default.

obx app identity:people init
obx app identity:people push init

POST /api/v1/identity/people

{
  "first_name": "Jane",
  "last_name": "Doe"
}

Successful response

{
  "id": "ppl_abc123def456",
  "first_name": "Jane",
  "last_name": "Doe",
  "avatar": "",
  "active": true,
  "system_owned": false,
  "primary_address_id": null,
  "primary_contact_method_id": null
}

Onboarding a person

Creates a person together with addresses, contact methods, and preferences in a single request. The first address is automatically set as the primary address. The first contact method is automatically set as the primary contact method.

obx app identity:people init
obx app identity:people push init

const person = await oblax.identity.person.onboard({
  first_name: "Jane",
  last_name: "Doe",
  addresses: [
    {
      label: "Home",
      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: "PERSONAL",
      value: "jane.doe@example.com",
    },
  ],
  preferences: [
    {
      key: "theme",
      value: "dark",
      value_type: "STRING",
    },
  ],
});

POST /api/v1/identity/people:onboard

{
  "first_name": "Jane",
  "last_name": "Doe",
  "addresses": [
    {
      "label": "Home",
      "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": "PERSONAL",
      "value": "jane.doe@example.com"
    }
  ],
  "preferences": [
    {
      "key": "theme",
      "value": "dark",
      "value_type": "STRING"
    }
  ]
}

Successful response

{
  "id": "ppl_abc123def456",
  "first_name": "Jane",
  "last_name": "Doe",
  "avatar": "",
  "active": true,
  "system_owned": false,
  "primary_address_id": "adr_xyz789uvw012",
  "primary_contact_method_id": "cnt_mno345pqr678"
}

Listing all people

Returns all people in the application. Each person object includes core identity fields but not sub-resources.

obx app identity:people list

GET /api/v1/identity/people

Successful response

[
  {
    "id": "ppl_abc123def456",
    "first_name": "Jane",
    "last_name": "Doe",
    "avatar": "https://example.com/avatars/jane.jpg",
    "active": true,
    "system_owned": false,
    "primary_address_id": "adr_xyz789uvw012",
    "primary_contact_method_id": "cnt_mno345pqr678"
  }
]

Getting a person

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

obx app identity:people pull ppl_abc123def456

GET /api/v1/identity/people/ppl_abc123def456

Successful response

{
  "id": "ppl_abc123def456",
  "first_name": "Jane",
  "last_name": "Doe",
  "avatar": "",
  "active": true,
  "system_owned": false,
  "primary_address_id": null,
  "primary_contact_method_id": null
}

Getting a persons full details

Returns the person object with all associated addresses, contact methods, and preferences embedded.

obx app identity:people pull ppl_abc123def456 --full

GET /api/v1/identity/people/ppl_abc123def456:full

Successful response

{
  "id": "ppl_abc123def456",
  "first_name": "Jane",
  "last_name": "Doe",
  "avatar": "",
  "active": true,
  "system_owned": false,
  "primary_address_id": "adr_xyz789uvw012",
  "primary_contact_method_id": "cnt_mno345pqr678",
  "addresses": [
    {
      "id": "adr_xyz789uvw012",
      "owner_id": "ppl_abc123def456",
      "label": "Home",
      "country": "US",
      "city": "San Francisco",
      "zipcode": "94105",
      "address": "Market Street",
      "address_number": "123",
      "longitude": -122.39,
      "latitude": 37.79
    }
  ],
  "contact_methods": [
    {
      "id": "cnt_mno345pqr678",
      "owner_id": "ppl_abc123def456",
      "contact_type": "EMAIL",
      "contact_kind": "PERSONAL",
      "value": "jane.doe@example.com"
    }
  ],
  "preferences": [
    {
      "id": "pre_stu901vwx234",
      "owner_id": "ppl_abc123def456",
      "key": "theme",
      "value": "dark",
      "value_type": "STRING"
    }
  ]
}

Updating a person

Updates the core fields of a person. Only the provided fields are modified.

obx app identity:people push ppl_abc123def456

Deleting a person

Removes a person and all associated addresses, contact methods, and preferences.

obx app identity:people delete ppl_abc123def456

Organization