#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 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"
}'

Phone numbers use E.164 format — 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.

{
  "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.
`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.

// 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");
});

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 on your dashboard, or send a confirmation text — see Send an 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.

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

A successful lookup returns 200 with the contact object. An unknown id returns 404 Not Found — see Errors for the full error shape.

#Next steps

Deep links — launch a call or pre-addressed text to a contact
Webhooks — react to inbound messages and call events
API reference — try the contacts endpoints live