Contact

Overview

VoIPBIN’s Contact API provides CRM-style contact management for organizing and enriching communication workflows. Each contact can hold multiple phone numbers, email addresses, and tags, enabling caller ID enrichment, routing decisions, and integration with external CRM systems.

With the Contact API you can:

Create and manage contacts with structured personal and company information
Store multiple phone numbers and email addresses per contact
Look up contacts by phone number (E.164) or email address
Assign tags for categorization and routing
Track contact origin and link to external CRM systems

How Contacts Work

Contacts act as the central identity record for people your platform communicates with.

Contact Architecture

+-----------------------------------------------------------------------+
|                        Contact System                                 |
+-----------------------------------------------------------------------+

+-------------------+
|     Contact       |
|  (identity record)|
+--------+----------+
         |
         | has many
         v
+--------+----------+--------+----------+--------+----------+
|                   |                   |                   |
v                   v                   v                   v
+----------+   +----------+   +----------+   +----------+
|  Phone   |   |  Email   |   |   Tags   |   | External |
| Numbers  |   | Addrs    |   |          |   |   ID     |
+----------+   +----------+   +----------+   +----------+
     |              |              |              |
     v              v              v              v
+---------+   +---------+   +---------+   +-----------+
| Lookup  |   | Lookup  |   | Filter  |   | CRM Sync  |
| by phone|   | by email|   | & route |   | & dedup   |
+---------+   +---------+   +---------+   +-----------+

Key Components

Contact: A person or entity with name, company, and job title
Phone Numbers: Multiple numbers per contact with type (mobile, work, home, fax, other) and E.164 normalization
Emails: Multiple addresses per contact with type (work, personal, other)
Tags: Labels for categorization and skill-based routing
Source: How the contact was created (manual, import, api, sync)
External ID: Reference to an external CRM record for deduplication

Contact Lookup

Find contacts by phone number or email address. This is useful for enriching incoming calls or messages with caller identity.

Lookup by Phone Number

Incoming Call: +15551234567
     |
     v
+--------------------------------------------+
| GET /contacts/lookup?phone=+15551234567    |
+--------------------------------------------+
     |
     v
+--------------------------------------------+
| Contact Found:                             |
|   Name: John Smith                         |
|   Company: Acme Corp                       |
|   Tags: [vip, enterprise]                  |
+--------------------------------------------+
     |
     v
Route to VIP queue / display caller info

Lookup by Email

Incoming Email: [email protected]
     |
     v
+--------------------------------------------+
| GET /contacts/[email protected]   |
+--------------------------------------------+
     |
     v
Contact matched → enrich conversation context

Phone numbers are matched in E.164 format for reliable international matching. Email addresses are matched case-insensitively.

Source Tracking

Each contact records how it was created, enabling analytics and deduplication.

Source Values

Source	Description
manual	Created by a user through the admin console or agent interface
import	Imported from a CSV file or bulk upload
api	Created programmatically via the API
sync	Synchronized from an external CRM system

External CRM Integration

The external_id field links a contact to its record in an external CRM system such as Salesforce, HubSpot, or Zoho.

Integration Pattern

External CRM                     VoIPBIN
+-------------------+            +-------------------+
| Salesforce        |            | Contact           |
| Contact ID:       |   sync     | external_id:      |
| 003Dn00000X1234   |----------->| 003Dn00000X1234   |
| Name: John Smith  |            | source: sync      |
+-------------------+            +-------------------+

Use Cases

Deduplication: Prevent duplicate contacts during re-imports by matching on external_id
Two-Way Sync: Keep contact data consistent between VoIPBIN and your CRM
Referential Integrity: Maintain links between VoIPBIN contacts and CRM records

Key Features and Use Cases

Contacts support various communication and organizational workflows.

Caller ID Enrichment

Incoming Call
     |
     v
Lookup contact by phone number
     |
     v
+--------------------------------------------+
| Display to agent:                          |
|   Caller: John Smith                       |
|   Company: Acme Corp                       |
|   Tags: enterprise, vip                    |
|   Previous interactions: 12                |
+--------------------------------------------+

Contact-Based Routing

Incoming Call from known contact
     |
     v
Lookup contact → check tags
     |
     v
+--------------------------------------------+
| Contact Tags: [enterprise, spanish]        |
|                                            |
| Route to: Enterprise Spanish Support Queue |
| Required agent tags: [enterprise, spanish] |
+--------------------------------------------+

Multi-Channel Contact History

Contact: John Smith
+--------------------------------------------+
| Phone Numbers:                             |
|   +15551234567 (mobile, primary)          |
|   +15559876543 (work)                     |
|                                            |
| Emails:                                    |
|   john@acme.com (work, primary)           |
|   john.smith@gmail.com (personal)         |
|                                            |
| All channels linked to one identity        |
+--------------------------------------------+

Best Practices

1. Phone Number Format

Always provide phone numbers in E.164 format (e.g., +15551234567)
The system normalizes numbers to E.164 for consistent matching
Mark one number as primary for outbound communication

2. Contact Organization

Use tags to categorize contacts (e.g., vip, enterprise, partner)
Set source accurately to track where contacts originate
Use external_id when integrating with external CRM systems

3. Lookup Best Practices

Use phone lookup for incoming call enrichment
Use email lookup for incoming message enrichment
Lookup returns the first matching contact

4. Data Quality

Keep display names consistent (first + last name)
Assign email types (work, personal) for proper channel selection
Remove outdated phone numbers and emails regularly

Structures

Contact

{
    "id": "<string>",
    "customer_id": "<string>",
    "first_name": "<string>",
    "last_name": "<string>",
    "display_name": "<string>",
    "company": "<string>",
    "job_title": "<string>",
    "source": "<string>",
    "external_id": "<string>",
    "phone_numbers": [<PhoneNumber>, ...],
    "emails": [<Email>, ...],
    "tag_ids": ["<string>", ...],
    "tm_create": "<string>",
    "tm_update": "<string>",
    "tm_delete": "<string>"
}

id: Contact’s unique identifier.
customer_id: Customer who owns this contact.
first_name: Contact’s first name.
last_name: Contact’s last name.
display_name: Contact’s display name.
company: Contact’s company or organization.
job_title: Contact’s job title.
source: How the contact was created. See Source.
external_id: Reference ID in an external CRM system (Salesforce, HubSpot, Zoho, etc.).
phone_numbers: Array of phone numbers. See PhoneNumber.
emails: Array of email addresses. See Email.
tag_ids: Array of tag UUIDs assigned to this contact.
tm_create: Timestamp of creation.
tm_update: Timestamp of last update.
tm_delete: Timestamp of deletion (soft delete).

Source

How the contact was created.

Value	Description
manual	Created by a user through the UI
import	Imported from a file or bulk upload
api	Created programmatically via the API
sync	Synchronized from an external CRM system

PhoneNumber

{
    "id": "<string>",
    "number": "<string>",
    "number_e164": "<string>",
    "type": "<string>",
    "is_primary": <boolean>,
    "tm_create": "<string>"
}

id: Phone number’s unique identifier.
number: Phone number as originally entered.
number_e164: Phone number normalized to E.164 format (e.g., “+15551234567”).
type: Phone number type. See PhoneNumberType.
is_primary: Whether this is the primary phone number for the contact.
tm_create: Timestamp of creation.

PhoneNumberType

Value	Description
mobile	Mobile/cell phone number
work	Work/office phone number
home	Home phone number
fax	Fax number
other	Other phone number type

Email

{
    "id": "<string>",
    "address": "<string>",
    "type": "<string>",
    "is_primary": <boolean>,
    "tm_create": "<string>"
}

id: Email’s unique identifier.
address: Email address (stored in lowercase).
type: Email address type. See EmailType.
is_primary: Whether this is the primary email for the contact.
tm_create: Timestamp of creation.

EmailType

Value	Description
work	Work/business email address
personal	Personal email address
other	Other email address type

Tutorial

Create a contact

Create a new contact with phone numbers, emails, and tags.

$ curl -X POST 'https://api.voipbin.net/v1.0/contacts?token=<YOUR_AUTH_TOKEN>' \
    --header 'Content-Type: application/json' \
    --data '{
        "first_name": "John",
        "last_name": "Smith",
        "display_name": "John Smith",
        "company": "Acme Corp",
        "job_title": "Account Manager",
        "source": "manual",
        "notes": "Key enterprise customer contact",
        "phone_numbers": [
            {
                "number": "+15551234567",
                "type": "mobile",
                "is_primary": true
            },
            {
                "number": "+15559876543",
                "type": "work",
                "is_primary": false
            }
        ],
        "emails": [
            {
                "address": "[email protected]",
                "type": "work",
                "is_primary": true
            }
        ],
        "tag_ids": [
            "uuid-for-enterprise-tag",
            "uuid-for-vip-tag"
        ]
    }'

{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "first_name": "John",
    "last_name": "Smith",
    "display_name": "John Smith",
    "company": "Acme Corp",
    "job_title": "Account Manager",
    "source": "manual",
    "external_id": "",
    "phone_numbers": [
        {
            "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
            "number": "+15551234567",
            "number_e164": "+15551234567",
            "type": "mobile",
            "is_primary": true,
            "tm_create": "2026-02-07T14:45:59.038962Z"
        },
        {
            "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
            "number": "+15559876543",
            "number_e164": "+15559876543",
            "type": "work",
            "is_primary": false,
            "tm_create": "2026-02-07T14:45:59.038962Z"
        }
    ],
    "emails": [
        {
            "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
            "address": "[email protected]",
            "type": "work",
            "is_primary": true,
            "tm_create": "2026-02-07T14:45:59.038962Z"
        }
    ],
    "tag_ids": [
        "uuid-for-enterprise-tag",
        "uuid-for-vip-tag"
    ],
    "tm_create": "2026-02-07T14:45:59.038962Z",
    "tm_update": null,
    "tm_delete": null
}

Get a list of contacts

Retrieve all contacts. Supports pagination with page_size and page_token.

$ curl -X GET 'https://api.voipbin.net/v1.0/contacts?token=<YOUR_AUTH_TOKEN>&page_size=10'

{
    "result": [
        {
            "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
            "first_name": "John",
            "last_name": "Smith",
            "display_name": "John Smith",
            "company": "Acme Corp",
            "job_title": "Account Manager",
            "source": "manual",
            "external_id": "",
            "phone_numbers": [
                {
                    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
                    "number": "+15551234567",
                    "number_e164": "+15551234567",
                    "type": "mobile",
                    "is_primary": true,
                    "tm_create": "2026-02-07T14:45:59.038962Z"
                }
            ],
            "emails": [
                {
                    "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
                    "address": "[email protected]",
                    "type": "work",
                    "is_primary": true,
                    "tm_create": "2026-02-07T14:45:59.038962Z"
                }
            ],
            "tag_ids": [
                "uuid-for-enterprise-tag"
            ],
            "tm_create": "2026-02-07T14:45:59.038962Z",
            "tm_update": "2026-02-07T14:45:59.038962Z",
            "tm_delete": null
        },
        ...
    ],
    "next_page_token": "2026-02-07T14:30:00.038962Z"
}

Get a specific contact

$ curl -X GET 'https://api.voipbin.net/v1.0/contacts/<contact-id>?token=<YOUR_AUTH_TOKEN>'

Update a contact

Update contact fields. Only the provided fields are changed.

$ curl -X PUT 'https://api.voipbin.net/v1.0/contacts/<contact-id>?token=<YOUR_AUTH_TOKEN>' \
    --header 'Content-Type: application/json' \
    --data '{
        "first_name": "John",
        "last_name": "Smith",
        "display_name": "John Smith (VIP)",
        "company": "Acme Corporation",
        "job_title": "Senior Account Manager",
        "notes": "Promoted to senior role in January"
    }'

Delete a contact

Soft-deletes the contact. The record is not permanently removed.

$ curl -X DELETE 'https://api.voipbin.net/v1.0/contacts/<contact-id>?token=<YOUR_AUTH_TOKEN>'

Lookup a contact by phone number

Find a contact by phone number in E.164 format.

$ curl -X GET 'https://api.voipbin.net/v1.0/contacts/lookup?token=<YOUR_AUTH_TOKEN>&phone=%2B15551234567'

Note: The + in the phone number must be URL-encoded as %2B.

Lookup a contact by email

Find a contact by email address. Matching is case-insensitive.

$ curl -X GET 'https://api.voipbin.net/v1.0/contacts/lookup?token=<YOUR_AUTH_TOKEN>&[email protected]'

Add a phone number

Add a new phone number to an existing contact.

$ curl -X POST 'https://api.voipbin.net/v1.0/contacts/<contact-id>/phone-numbers?token=<YOUR_AUTH_TOKEN>' \
    --header 'Content-Type: application/json' \
    --data '{
        "number": "+15553334444",
        "type": "home",
        "is_primary": false
    }'

Update a phone number

Update an existing phone number’s details.

$ curl -X PUT 'https://api.voipbin.net/v1.0/contacts/<contact-id>/phone-numbers/<phone-number-id>?token=<YOUR_AUTH_TOKEN>' \
    --header 'Content-Type: application/json' \
    --data '{
        "number": "+15553334444",
        "type": "mobile",
        "is_primary": true
    }'

Remove a phone number

$ curl -X DELETE 'https://api.voipbin.net/v1.0/contacts/<contact-id>/phone-numbers/<phone-number-id>?token=<YOUR_AUTH_TOKEN>'

Add an email address

Add a new email address to an existing contact.

$ curl -X POST 'https://api.voipbin.net/v1.0/contacts/<contact-id>/emails?token=<YOUR_AUTH_TOKEN>' \
    --header 'Content-Type: application/json' \
    --data '{
        "address": "[email protected]",
        "type": "personal",
        "is_primary": false
    }'

Update an email address

Update an existing email address’s details.

$ curl -X PUT 'https://api.voipbin.net/v1.0/contacts/<contact-id>/emails/<email-id>?token=<YOUR_AUTH_TOKEN>' \
    --header 'Content-Type: application/json' \
    --data '{
        "address": "[email protected]",
        "type": "personal",
        "is_primary": true
    }'

Remove an email address

$ curl -X DELETE 'https://api.voipbin.net/v1.0/contacts/<contact-id>/emails/<email-id>?token=<YOUR_AUTH_TOKEN>'

Add a tag

Assign a tag to a contact for categorization or routing.

$ curl -X POST 'https://api.voipbin.net/v1.0/contacts/<contact-id>/tags?token=<YOUR_AUTH_TOKEN>' \
    --header 'Content-Type: application/json' \
    --data '{
        "tag_id": "uuid-for-enterprise-tag"
    }'

Remove a tag

$ curl -X DELETE 'https://api.voipbin.net/v1.0/contacts/<contact-id>/tags/<tag-id>?token=<YOUR_AUTH_TOKEN>'

Contact

Overview

How Contacts Work

Contact Lookup

Source Tracking

External CRM Integration

Key Features and Use Cases

Best Practices

Related Documentation

Structures

Contact

Source

PhoneNumber

PhoneNumberType

Email

EmailType

Tutorial

Create a contact

Get a list of contacts

Get a specific contact

Update a contact

Delete a contact

Lookup a contact by phone number

Lookup a contact by email

Add a phone number

Update a phone number

Remove a phone number

Add an email address

Update an email address

Remove an email address

Add a tag

Remove a tag