Families & Fields

Families are schema definitions that describe the structure of entities in your workspace. Think of them as database table definitions -- each family has a code, a label, and a set of typed fields. Entities are instances of a family.

Families support various field types including text, number, date, email, phone, select, multiselect, relation, boolean, and more. Each field can be marked as required, searchable, or filterable.

GET/core/api/v1/families

List all families

Retrieve all family definitions available in the current workspace. Each family includes its fields and pipeline configurations.

Response fields

Name
code
Type
string
Description
The unique code identifying the family (e.g. contact, company, deal).
Name
label
Type
string
Description
The human-readable name of the family.
Name
fields
Type
array
Description
Array of field definitions. Each field has code, type, required, label, and optional configuration.
Name
pipelines
Type
array
Description
Array of pipeline definitions associated with this family. Pipelines define status workflows (e.g. new -> in_progress -> closed).

GET

/core/api/v1/families

curl https://your-sphere.example.com/core/api/v1/families \
  -H "Authorization: Bearer {token}"

Response

{
  "data": [
    {
      "code": "contact",
      "label": "Contact",
      "fields": [
        {
          "code": "first_name",
          "type": "text",
          "label": "First Name",
          "required": true,
          "searchable": true
        },
        {
          "code": "last_name",
          "type": "text",
          "label": "Last Name",
          "required": true,
          "searchable": true
        },
        {
          "code": "email",
          "type": "email",
          "label": "Email",
          "required": false,
          "searchable": true
        },
        {
          "code": "phone",
          "type": "phone",
          "label": "Phone",
          "required": false,
          "searchable": false
        }
      ],
      "pipelines": [
        {
          "code": "default",
          "label": "Default Pipeline",
          "statuses": ["new", "active", "archived"]
        }
      ]
    },
    {
      "code": "company",
      "label": "Company",
      "fields": [
        {
          "code": "name",
          "type": "text",
          "label": "Company Name",
          "required": true,
          "searchable": true
        },
        {
          "code": "industry",
          "type": "select",
          "label": "Industry",
          "required": false,
          "options": ["Technology", "Finance", "Healthcare", "Other"]
        }
      ],
      "pipelines": []
    }
  ]
}

GET/core/api/v1/families/{code}

Get family details

Retrieve a single family definition by its code, including all field definitions and pipeline configurations.

Path parameters

Name
code
Type
string
Description
The unique code of the family (e.g. contact, company).

GET

/core/api/v1/families/{code}

curl https://your-sphere.example.com/core/api/v1/families/contact \
  -H "Authorization: Bearer {token}"

Response

{
  "data": {
    "code": "contact",
    "label": "Contact",
    "fields": [
      {
        "code": "first_name",
        "type": "text",
        "label": "First Name",
        "required": true,
        "searchable": true,
        "filterable": true
      },
      {
        "code": "last_name",
        "type": "text",
        "label": "Last Name",
        "required": true,
        "searchable": true,
        "filterable": true
      },
      {
        "code": "email",
        "type": "email",
        "label": "Email",
        "required": false,
        "searchable": true,
        "filterable": false
      },
      {
        "code": "phone",
        "type": "phone",
        "label": "Phone",
        "required": false,
        "searchable": false,
        "filterable": false
      },
      {
        "code": "company",
        "type": "relation",
        "label": "Company",
        "required": false,
        "target_family": "company"
      }
    ],
    "pipelines": [
      {
        "code": "default",
        "label": "Default Pipeline",
        "statuses": ["new", "active", "archived"]
      }
    ]
  }
}

GET/core/api/v1/families/{code}/fields

List family fields

Retrieve only the field definitions for a specific family. This is a convenience endpoint when you only need the schema without pipeline information.

Path parameters

Name
code
Type
string
Description
The unique code of the family.

Field type reference

Name
text
Type
field type
Description
Plain text string.
Name
number
Type
field type
Description
Numeric value (integer or decimal).
Name
date
Type
field type
Description
ISO 8601 date (YYYY-MM-DD).
Name
email
Type
field type
Description
Email address with validation.
Name
phone
Type
field type
Description
Phone number string.
Name
select
Type
field type
Description
Single value from predefined options.
Name
multiselect
Type
field type
Description
Multiple values from predefined options.
Name
boolean
Type
field type
Description
True or false value.
Name
relation
Type
field type
Description
Reference to another entity (has target_family).

GET

/core/api/v1/families/{code}/fields

curl https://your-sphere.example.com/core/api/v1/families/contact/fields \
  -H "Authorization: Bearer {token}"

Response

{
  "data": [
    {
      "code": "first_name",
      "type": "text",
      "label": "First Name",
      "required": true,
      "searchable": true,
      "filterable": true
    },
    {
      "code": "last_name",
      "type": "text",
      "label": "Last Name",
      "required": true,
      "searchable": true,
      "filterable": true
    },
    {
      "code": "email",
      "type": "email",
      "label": "Email",
      "required": false,
      "searchable": true,
      "filterable": false
    },
    {
      "code": "phone",
      "type": "phone",
      "label": "Phone",
      "required": false,
      "searchable": false,
      "filterable": false
    },
    {
      "code": "company",
      "type": "relation",
      "label": "Company",
      "required": false,
      "target_family": "company"
    }
  ]
}