Contact

Manage contacts with phone numbers, names, and tags for use in campaigns and call routing. Contacts serve as the address book for outbound operations and caller identification.

API Reference: Contact endpoints

Overview

Note

AI Context

Complexity: Low
Cost: Free (contacts are organizational records with no per-operation charges)
Async: No. All contact CRUD operations are synchronous and return the result immediately.

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.

Note

AI Implementation Hint

When using phone number lookup, the + character must be URL-encoded as %2B. For example: GET /contacts/lookup?phone=%2B15551234567. Omitting this encoding will result in the + being interpreted as a space and the lookup will fail.

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 (UUID): The contact’s unique identifier. Returned when creating via POST /contacts or listing via GET /contacts.
customer_id (UUID): The customer who owns this contact. Obtained from GET /customers.
first_name (String): Contact’s first name.
last_name (String): Contact’s last name.
display_name (String): Contact’s display name, typically “First Last”. Used for caller ID enrichment.
company (String): Contact’s company or organization name.
job_title (String): Contact’s job title or role.
source (enum string): How the contact was created. See Source.
external_id (String): Reference ID in an external CRM system (Salesforce, HubSpot, Zoho, etc.). Used for deduplication and two-way sync.
phone_numbers (Array of Object): Array of phone numbers associated with this contact. See PhoneNumber.
emails (Array of Object): Array of email addresses associated with this contact. See Email.
tag_ids (Array of UUID): Array of tag UUIDs assigned to this contact. Each tag ID is obtained from GET /tags.
tm_create (string, ISO 8601): Timestamp when the contact was created.
tm_update (string, ISO 8601): Timestamp of the last update. null if never updated.
tm_delete (string, ISO 8601): Timestamp of deletion (soft delete). null if not deleted.

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 (UUID): The phone number entry’s unique identifier. Returned when adding via POST /contacts/{id}/phone-numbers.
number (String): Phone number as originally entered by the user.
number_e164 (String): Phone number normalized to E.164 format (e.g., +15551234567). Used for lookup matching.
type (enum string): Phone number type. See PhoneNumberType.
is_primary (Boolean): Whether this is the primary phone number for the contact. Only one number should be marked primary.
tm_create (string, ISO 8601): Timestamp when the phone number was added.

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 (UUID): The email entry’s unique identifier. Returned when adding via POST /contacts/{id}/emails.
address (String): Email address (stored and matched in lowercase).
type (enum string): Email address type. See EmailType.
is_primary (Boolean): Whether this is the primary email for the contact. Only one email should be marked primary.
tm_create (string, ISO 8601): Timestamp when the email address was added.

EmailType

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

Tutorial

Before working with contacts, you need:

An authentication token. Obtain one via POST /auth/login or use an access key from GET /accesskeys.
(Optional) Tag IDs (UUIDs) for categorization. Create tags via POST /tags or obtain existing ones from GET /tags.
(Optional) Phone numbers in E.164 format (e.g., +15551234567) for phone number entries.

Note

AI Implementation Hint

Phone numbers are automatically normalized to E.164 format in the number_e164 field. When using the phone lookup endpoint (GET /contacts/lookup?phone=...), the + character must be URL-encoded as %2B. Contact operations are free and synchronous.

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