Skip to main content
GET
/
v1
/
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=user@example.com&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)

​
email
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[]
​
meta
object
⌘I