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 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
    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": "[email protected]",
    "phone": "+4520123456",
    "phone_formatted": "+45 20 12 34 56",
    "company_name": "Stephenson ApS",
    "note": "Always asks for the engineering team.",
    "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": "[email protected]",
    "phone": "+4520123456",
    "company_name": "Stephenson ApS",
    "note": "Always asks for the engineering team."
  }'

Response

{
  "id": "01JVWX...",
  "name": "Niklas Stephenson",
  "email": "[email protected]",
  "phone": "+4520123456",
  "phone_formatted": "+45 20 12 34 56",
  "company_name": "Stephenson ApS",
  "note": "Always asks for the engineering team.",
  "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": "[email protected]",
  "phone": "+4520123456",
  "phone_formatted": "+45 20 12 34 56",
  "company_name": "Stephenson ApS",
  "note": "Always asks for the engineering team.",
  "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": "[email protected]",
  "phone": "+4520123456",
  "phone_formatted": "+45 20 12 34 56",
  "company_name": "Stephenson ApS",
  "note": "Prefers email follow-ups.",
  "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.