Phone.inc

Contacts

Contacts are your address book. Save a phone number once and Phone.inc will label every matching call with the contact's name, the company they work for, and any note you wrote down. The first time a new number calls in (or you call it), Phone.inc also creates a contact automatically — with no name until you fill one in.

The contact model

A contact represents a person (or business) you talk to. Phone numbers are unique per company and stored in E.164 format.

Properties

  • Name
    id
    Type
    string
    Description

    Unique public identifier for the contact.

  • Name
    name
    Type
    string
    Description

    Display name for the contact. Optional — useful when you have a phone number but don't yet know who it belongs to.

  • Name
    email
    Type
    string
    Description

    Email address. Optional. Format-validated when present.

  • Name
    phone
    Type
    string
    Description

    Phone number in E.164 format (e.g. +14155552671). Required and unique per company. Inputs with spaces or formatting characters are normalized before being saved.

  • Name
    phone_formatted
    Type
    string
    Description

    The phone number rendered in international format with spaces (e.g. +1 415-555-2671). Read-only.

  • Name
    company_name
    Type
    string
    Description

    The contact's employer or business. Optional.

  • Name
    note
    Type
    string
    Description

    Free-form note. Up to 10,000 characters.

  • Name
    last_contact_at
    Type
    timestamp
    Description

    ISO 8601 timestamp of the most recent call, voicemail, or message involving this contact. null until the company has recorded activity with them. Used to order the dashboard Inbox.

  • Name
    created_at
    Type
    timestamp
    Description

    ISO 8601 timestamp of when the contact was created.

  • Name
    updated_at
    Type
    timestamp
    Description

    ISO 8601 timestamp of the last update.

Want notifications when contacts change? Subscribe to contact.created, contact.updated, and contact.deleted on the Webhooks endpoint.

GET/v1/contacts

List contacts

Returns every contact in your company, newest first.

Optional attributes

  • Name
    phone
    Type
    string
    Description

    Filter to the single contact whose phone number matches the given input. The value is normalized to E.164 before lookup, so +45 20 12 34 56 and +4520123456 both work. Returns an empty list if the input can't be normalized to a phone number.

Request

GET
/v1/contacts
curl https://app.phone.inc/api/v1/contacts \
  -H "X-Api-Key: $PHONE_INC_API_KEY"

Response

[
  {
    "id": "01JVWX...",
    "name": "Niklas Stephenson",
    "email": "niklas@example.com",
    "phone": "+4520123456",
    "phone_formatted": "+45 20 12 34 56",
    "company_name": "Stephenson ApS",
    "note": "Always asks for the engineering team.",
    "last_contact_at": "2026-06-12T14:22:00Z",
    "created_at": "2026-06-10T10:00:00Z",
    "updated_at": "2026-06-10T10:00:00Z"
  }
]
POST/v1/contacts

Create a contact

Adds a new contact. The phone number must be unique within your company — creating a second contact with the same number returns 422 Unprocessable Entity.

Required attributes

  • Name
    phone
    Type
    string
    Description

    Phone number in E.164 format. Spaces and other non-digit characters are stripped before validation, so +45 20 12 34 56 is accepted.

Optional attributes

  • Name
    name
    Type
    string
    Description

    Display name.

  • Name
    email
    Type
    string
    Description

    Email address. Validated when present.

  • Name
    company_name
    Type
    string
    Description

    The contact's employer or business.

  • Name
    note
    Type
    string
    Description

    Free-form note (up to 10,000 characters).

Request

POST
/v1/contacts
curl -X POST https://app.phone.inc/api/v1/contacts \
  -H "X-Api-Key: $PHONE_INC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Niklas Stephenson",
    "email": "niklas@example.com",
    "phone": "+4520123456",
    "company_name": "Stephenson ApS",
    "note": "Always asks for the engineering team."
  }'

Response

{
  "id": "01JVWX...",
  "name": "Niklas Stephenson",
  "email": "niklas@example.com",
  "phone": "+4520123456",
  "phone_formatted": "+45 20 12 34 56",
  "company_name": "Stephenson ApS",
  "note": "Always asks for the engineering team.",
  "last_contact_at": null,
  "created_at": "2026-06-10T10:00:00Z",
  "updated_at": "2026-06-10T10:00:00Z"
}
GET/v1/contacts/:id

Retrieve a contact

Returns a single contact by its ID. Returns 404 Not Found if the contact doesn't exist or belongs to a different company.

Request

GET
/v1/contacts/:id
curl https://app.phone.inc/api/v1/contacts/01JVWX... \
  -H "X-Api-Key: $PHONE_INC_API_KEY"

Response

{
  "id": "01JVWX...",
  "name": "Niklas Stephenson",
  "email": "niklas@example.com",
  "phone": "+4520123456",
  "phone_formatted": "+45 20 12 34 56",
  "company_name": "Stephenson ApS",
  "note": "Always asks for the engineering team.",
  "last_contact_at": "2026-06-12T14:22:00Z",
  "created_at": "2026-06-10T10:00:00Z",
  "updated_at": "2026-06-10T10:00:00Z"
}
PATCH/v1/contacts/:id

Update a contact

Updates one or more fields on an existing contact. Send only the fields you want to change.

Optional attributes

  • Name
    name
    Type
    string
    Description

    New display name.

  • Name
    email
    Type
    string
    Description

    New email address.

  • Name
    phone
    Type
    string
    Description

    New phone number. Must remain unique within your company.

  • Name
    company_name
    Type
    string
    Description

    New employer or business name.

  • Name
    note
    Type
    string
    Description

    Replace the existing note.

Request

PATCH
/v1/contacts/:id
curl -X PATCH https://app.phone.inc/api/v1/contacts/01JVWX... \
  -H "X-Api-Key: $PHONE_INC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"note": "Prefers email follow-ups."}'

Response

{
  "id": "01JVWX...",
  "name": "Niklas Stephenson",
  "email": "niklas@example.com",
  "phone": "+4520123456",
  "phone_formatted": "+45 20 12 34 56",
  "company_name": "Stephenson ApS",
  "note": "Prefers email follow-ups.",
  "last_contact_at": "2026-06-12T14:22:00Z",
  "created_at": "2026-06-10T10:00:00Z",
  "updated_at": "2026-06-10T14:30:00Z"
}
DELETE/v1/contacts/:id

Delete a contact

Permanently removes a contact. Calls already in your archive keep their from/to numbers but lose the contact link.

Request

DELETE
/v1/contacts/:id
curl -X DELETE https://app.phone.inc/api/v1/contacts/01JVWX... \
  -H "X-Api-Key: $PHONE_INC_API_KEY"

Returns 204 No Content on success.