<!-- VanceTel docs · /docs/contacts -->

# Contacts

Contacts let you push people into the shared softphone directory from your own software. A contact created through the API resolves caller ID across the softphone: when that number calls or texts, your team sees the name, company and details instead of a raw number.

  Contacts are a **write- and lookup-oriented** resource. You create a contact and you retrieve
  it by id. The softphone app surfaces the full directory and conversation history in real time.

## Create a contact

A single `POST` to `/v1/contacts` adds a person to the directory. Only `phone` is required; `name`, `email` and `company` are optional but improve caller-ID resolution.

**curl**

```bash
curl https://api.netexem.com/v1/contacts \
  -H "Authorization: Bearer $NETEXEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "phone": "+15557654321",
    "email": "jane@example.com",
    "company": "Acme Co"
  }'
```

**Node**

```ts
const res = await fetch("https://api.netexem.com/v1/contacts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NETEXEM_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Jane Doe",
    phone: "+15557654321",
    email: "jane@example.com",
    company: "Acme Co",
  }),
});
const contact = await res.json();
```

**Python**

```python
import os, requests

res = requests.post(
    "https://api.netexem.com/v1/contacts",
    headers={"Authorization": f"Bearer {os.environ['NETEXEM_API_KEY']}"},
    json={
        "name": "Jane Doe",
        "phone": "+15557654321",
        "email": "jane@example.com",
        "company": "Acme Co",
    },
)
contact = res.json()
```

  Phone numbers use [E.164 format](/developers/glossary/e164) — a leading `+` and country code, e.g.
  `+15557654321`.

## The contact object

A successful create returns `201` with the stored contact. The same shape is returned when you retrieve a contact later.

```json
{
  "id": "ct_01h…",
  "name": "Jane Doe",
  "phone": "+15557654321",
  "email": "jane@example.com",
  "company": "Acme Co",
  "createdAt": "2026-05-31T14:02:11Z"
}
```

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string | Unique contact id, prefixed `ct_`. |
| `name` | string | Display name shown for caller ID. |
| `phone` | string | The contact's number in [E.164](/developers/glossary/e164). |
| `email` | string | Optional email address. |
| `company` | string | Optional company name. |
| `createdAt` | string | ISO 8601 timestamp of creation. |

## From a web form

A common pattern: a visitor submits a form on your website, your server creates a contact, and the next time that person calls or texts the softphone already knows who they are.

The flow is two hops — the browser posts the form to **your** server, and your server (where the API key lives) creates the contact. Never call the API directly from the browser; that would expose your key. See [Authentication](/developers/docs/authentication).

**Node**

```ts
// POST /lead — your server's form handler
app.post("/lead", async (req, res) => {
  const { name, phone, email, company } = req.body;

  // Create the contact so the softphone resolves caller ID
  await fetch("https://api.netexem.com/v1/contacts", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.NETEXEM_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ name, phone, email, company }),
  });

  res.redirect("/thanks");
});
```

**Python**

```python
import os, requests
from flask import request, redirect

# POST /lead — your server's form handler
@app.post("/lead")
def lead():
    payload = {
        "name": request.form["name"],
        "phone": request.form["phone"],
        "email": request.form.get("email"),
        "company": request.form.get("company"),
    }

    # Create the contact so the softphone resolves caller ID
    requests.post(
        "https://api.netexem.com/v1/contacts",
        headers={"Authorization": f"Bearer {os.environ['NETEXEM_API_KEY']}"},
        json=payload,
    )

    return redirect("/thanks")
```

  Once created, the contact is shared across the softphone. An inbound call or text from that
  number now shows the person's name and company instead of a bare number.

To follow up immediately, pair this with a [deep link](/developers/docs/deep-links) on your dashboard, or send a confirmation text — see [Send an SMS](/developers/docs/sms).

## Retrieve a contact

Fetch a contact by id with a `GET` to `/v1/contacts/{id}`. Store the `id` from the create response to look it up later.

```bash
curl https://api.netexem.com/v1/contacts/ct_01h… \
  -H "Authorization: Bearer $NETEXEM_API_KEY"
```

A successful lookup returns `200` with the [contact object](#the-contact-object). An unknown id returns `404 Not Found` — see [Errors](/developers/docs/errors) for the full error shape.

## Next steps

- [Deep links](/developers/docs/deep-links) — launch a call or pre-addressed text to a contact
- [Webhooks](/developers/docs/webhooks) — react to inbound messages and call events
- [API reference](/developers/docs/api-reference) — try the contacts endpoints live