Get phones

curl --request GET \
  --url https://api.wellapp.ai/v1/phones \
  --header 'Authorization: <authorization>'

{
  "data": [
    {
      "type": "phone",
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "attributes": {
        "country_code": 1,
        "national_number": "4155552671",
        "e164_number": "+14155552671",
        "label": "work",
        "is_primary": true,
        "is_verified": true,
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z"
      },
      "relationships": {
        "persons": {
          "data": [
            {
              "type": "people",
              "id": "people1"
            }
          ]
        },
        "companies": {
          "data": [
            {
              "type": "company",
              "id": "company_tenant"
            }
          ]
        },
        "workspaces": {
          "data": [
            {
              "type": "workspace",
              "id": "workspace_sales"
            },
            {
              "type": "workspace",
              "id": "550e8400-e29b-41d4-a716-446655440000"
            }
          ]
        }
      }
    }
  ],
  "included": [
    {
      "type": "people",
      "id": "people1",
      "attributes": {
        "first_name": "John",
        "last_name": "Doe",
        "full_name": "John Doe",
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z"
      }
    },
    {
      "type": "company",
      "id": "company_tenant",
      "attributes": {
        "name": "Acme Corporation",
        "description": "Leading technology company",
        "locale": "en",
        "domain_name_primary_link_url": "acme.com",
        "created_at": "2023-12-01T09:00:00Z",
        "updated_at": "2023-12-01T09:00:00Z"
      }
    },
    {
      "type": "workspace",
      "id": "workspace_sales",
      "attributes": {
        "name": "Sales Team Workspace",
        "description": "Workspace for sales activities",
        "avatar_color": "#FF6B35",
        "external_workspace_id": "fygr_123",
        "auto_extract_enabled": true,
        "created_at": "2024-01-10T08:15:00Z",
        "updated_at": "2024-01-10T08:15:00Z"
      }
    },
    {
      "type": "workspace",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "attributes": {
        "name": "Marketing Team Workspace",
        "description": "Workspace for marketing campaigns",
        "avatar_color": "#4A90E2",
        "external_workspace_id": "mkt_workspace_001",
        "auto_extract_enabled": false,
        "created_at": "2024-01-12T14:45:00Z",
        "updated_at": "2024-01-12T14:45:00Z"
      }
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 20,
    "total_pages": 1
  }
}

Phones

Get Phones

Retrieve a list of phone numbers with advanced filtering, sorting, and include capabilities. This endpoint supports:

Default behavior: Returns phone numbers with basic information (IDs only for relationships).

Trailing slashes: Works with or without trailing slashes ’/’.

Include functionality: Use the include parameter to get detailed relationship data.

Date filtering: Filter by creation, update, or deletion date ranges.

Relationship filtering: Filter by related entities using various identifiers.

Contact filtering: Filter by contact information and verification status.

Company filtering: Filter by company registration details.

Phone filtering: Filter by primary status, verification, and label.

Sorting: Sort results by date fields in ascending or descending order.

GET

phones

Get phones

curl --request GET \
  --url https://api.wellapp.ai/v1/phones \
  --header 'Authorization: <authorization>'

{
  "data": [
    {
      "type": "phone",
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "attributes": {
        "country_code": 1,
        "national_number": "4155552671",
        "e164_number": "+14155552671",
        "label": "work",
        "is_primary": true,
        "is_verified": true,
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z"
      },
      "relationships": {
        "persons": {
          "data": [
            {
              "type": "people",
              "id": "people1"
            }
          ]
        },
        "companies": {
          "data": [
            {
              "type": "company",
              "id": "company_tenant"
            }
          ]
        },
        "workspaces": {
          "data": [
            {
              "type": "workspace",
              "id": "workspace_sales"
            },
            {
              "type": "workspace",
              "id": "550e8400-e29b-41d4-a716-446655440000"
            }
          ]
        }
      }
    }
  ],
  "included": [
    {
      "type": "people",
      "id": "people1",
      "attributes": {
        "first_name": "John",
        "last_name": "Doe",
        "full_name": "John Doe",
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z"
      }
    },
    {
      "type": "company",
      "id": "company_tenant",
      "attributes": {
        "name": "Acme Corporation",
        "description": "Leading technology company",
        "locale": "en",
        "domain_name_primary_link_url": "acme.com",
        "created_at": "2023-12-01T09:00:00Z",
        "updated_at": "2023-12-01T09:00:00Z"
      }
    },
    {
      "type": "workspace",
      "id": "workspace_sales",
      "attributes": {
        "name": "Sales Team Workspace",
        "description": "Workspace for sales activities",
        "avatar_color": "#FF6B35",
        "external_workspace_id": "fygr_123",
        "auto_extract_enabled": true,
        "created_at": "2024-01-10T08:15:00Z",
        "updated_at": "2024-01-10T08:15:00Z"
      }
    },
    {
      "type": "workspace",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "attributes": {
        "name": "Marketing Team Workspace",
        "description": "Workspace for marketing campaigns",
        "avatar_color": "#4A90E2",
        "external_workspace_id": "mkt_workspace_001",
        "auto_extract_enabled": false,
        "created_at": "2024-01-12T14:45:00Z",
        "updated_at": "2024-01-12T14:45:00Z"
      }
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 20,
    "total_pages": 1
  }
}

Complex Usage Example

Advanced Phone Number Filtering with Full Context

This example demonstrates advanced filtering with multiple parameters, relationship inclusion, verification status, and sorting for retrieving phone numbers:

curl -X GET "https://api.well.com/v1/phones?include=persons,companies,workspaces&workspace_id=550e8400-e29b-41d4-a716-446655440000&company_id=550e8400-e29b-41d4-a716-446655440001&is_verified=true&is_primary=true&label=work&phone_number=+1415555&[email protected]&created_at_from=2023-01-01T00:00:00Z&created_at_to=2023-12-31T23:59:59Z&updated_at_from=2023-06-01T00:00:00Z&sort=-created_at&page[limit]=25&page[cursor]=eyJjcmVhdGVkX2F0IjoiMjAyMy0xMS0wMlQxMDozMDowMFoiLCJpZCI6InBob25lOS11dWlkIn0=" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Headers

Authorization

string

required

Bearer token for authentication

Query Parameters

include

string

Comma-separated list of related resources to include with detailed attributes. Available options: persons, companies, workspaces

created_at_from

string<date-time>

Filter phones created on or after this datetime (ISO 8601 format)

created_at_to

string<date-time>

Filter phones created on or before this datetime (ISO 8601 format)

updated_at_from

string<date-time>

Filter phones updated on or after this datetime (ISO 8601 format)

updated_at_to

string<date-time>

Filter phones updated on or before this datetime (ISO 8601 format)

workspace_id

string<uuid>

Filter phones by workspace UUID

external_workspace_id

string

Filter phones by external workspace identifier

people_id

string<uuid>

Filter phones by person UUID

phone_number

string

Filter phones by phone number in E.164 format (e.g., +14155552671)

string<email>

Filter phones by associated person's email address

company_id

string<uuid>

Filter phones by company UUID

registration_tax_id

string

Filter phones by company registration tax ID

registration_registered_value

string

Filter phones by company registration value

is_primary

boolean

default:true

Filter phones by primary status (true/false)

is_verified

boolean

default:true

Filter phones by verification status (true/false)

label

enum<string>

default:work

Filter phones by label type

Available options:

work,

home,

mobile,

fax,

other

sort

enum<string>

default:-created_at

Sort phones by date field. Use '-' prefix for descending order (e.g., '-created_at' for newest first)

Available options:

created_at,

updated_at,

-created_at

page[limit]

integer

default:20

Number of phones per page (1-100)

Required range: 1 <= x <= 100

page[cursor]

string

Cursor for pagination to get next set of results

Response

Phones retrieved successfully

data

object[]

Show child attributes

data.type

string

Allowed value: "phone"

data.id

string<uuid>

UUID of the phone

data.attributes

object

Show child attributes

data.attributes.number

string

Full international phone number in E164 format

Example:

"+14155552671"

data.attributes.label

enum<string>

Phone label type. See all available labels for complete list.

Available options:

work,

personal,

other,

...

data.attributes.is_primary

boolean

Whether this is the primary phone number

data.attributes.created_at

string<date-time>

Timestamp when the phone was created

data.relationships

object

Show child attributes

data.relationships.persons

object

Show child attributes

data.relationships.persons.data

object[]

Show child attributes

data.relationships.persons.data.type

enum<string>

Available options:

people

data.relationships.persons.data.id

string<uuid>

UUID of the people

data.relationships.companies

object

Show child attributes

data.relationships.companies.data

object[]

Show child attributes

data.relationships.companies.data.type

enum<string>

Available options:

company

data.relationships.companies.data.id

string<uuid>

UUID of the company

data.relationships.workspaces

object

Show child attributes

data.relationships.workspaces.data

object[]

Option 1
Option 2

Show child attributes

data.relationships.workspaces.data.type

enum<string>

Available options:

workspace

data.relationships.workspaces.data.external_workspace_id

string

External workspace identifier

data.included

object

Show child attributes

data.included.persons

object

Show child attributes

data.included.persons.data

object[]

Show child attributes

data.included.persons.data.type

string

Allowed value: "people"

data.included.persons.data.id

string<uuid>

data.included.persons.data.attributes

object

Person attribute data

Show child attributes

data.included.persons.data.attributes.first_name

string

required

Person's first name

Required string length: 1 - 100

Example:

"Marie"

data.included.persons.data.attributes.last_name

string

required

Person's last name

Required string length: 1 - 100

Example:

"Dubois"

data.included.persons.data.attributes.created_at

string<date-time>

required

Person creation timestamp (UTC)

Example:

"2024-01-15T10:30:00Z"

data.included.persons.data.attributes.full_name

string

Auto-computed full name (first + last)

Example:

"Marie Dubois"

data.included.persons.data.attributes.updated_at

string<date-time> | null

Last modification timestamp (UTC)

Example:

"2024-01-16T14:20:00Z"

data.included.companies

object

Show child attributes

data.included.companies.data

object[]

Show child attributes

data.included.companies.data.type

string

Allowed value: "company"

data.included.companies.data.id

string<uuid>

data.included.companies.data.attributes

object

Show child attributes

data.included.companies.data.attributes.description

string

data.included.companies.data.attributes.domain_name_primary_link_url

string<url>

The domain url from the website or email address of the company. Used as unique identifier in some cases.

Maximum string length: 500

data.included.companies.data.attributes.tax_id

object

Show child attributes

data.included.companies.data.attributes.tax_id.value

string

Tax ID issued by local or national tax authority.

data.included.companies.data.attributes.tax_id.type

string

Type of tax ID, useful for applying formatting and validation rules.

data.included.companies.data.attributes.registration

object

Show child attributes

data.included.companies.data.attributes.registration.trade_name

string

Commercial or branding name (if different from registered name).

data.included.companies.data.attributes.registration.registered_name

string

Legal company name.

Required string length: 1 - 100

data.included.companies.data.attributes.registration_number

object

Show child attributes

data.included.companies.data.attributes.registration_number.business_type

string

Legal entity structure type.

data.included.companies.data.attributes.registration_number.value

string

Official company registration number.

data.included.companies.data.attributes.registration_number.registry_name

string

Name of the official registration body.

data.included.companies.data.attributes.registration_number.registry_country

string

Country of the registry authority. (string (ISO 3166-1 alpha-2))

data.included.companies.data.attributes.workspace_id

string<uuid>

UUID of the workspace associated with this company

data.included.companies.data.attributes.created_at

string<date-time>

data.included.companies.data.attributes.updated_at

string<date-time>

data.included.workspaces

object

Show child attributes

data.included.workspaces.data

object[]

Show child attributes

data.included.workspaces.data.type

string

Allowed value: "workspace"

data.included.workspaces.data.id

string<uuid>

data.included.workspaces.data.attributes

object

Show child attributes

data.included.workspaces.data.attributes.name

string

Workspace name

data.included.workspaces.data.attributes.desription

string

Workspace description

data.included.workspaces.data.attributes.external_workspace_id

string<uuid>

external workspace id

data.included.workspaces.data.attributes.avatar_color

string<colors>

Color of the avatar

data.included.workspaces.data.attributes.created_at

string<date-time>

Timestamp when the workspace was created

data.included.workspaces.data.attributes.updated_at

string<date-time>

Timestamp when the workspace was last updated

Main Resources

Atomic Resources

System

Get Phones

Complex Usage Example

Advanced Phone Number Filtering with Full Context

Headers

Query Parameters

Response

Main Resources

Atomic Resources

System

​Complex Usage Example

​Advanced Phone Number Filtering with Full Context

Headers

Query Parameters

Response

Complex Usage Example

Advanced Phone Number Filtering with Full Context