---
title: Contacts API
description: Upsert normalized contact records and import contacts in bulk.
---

import Endpoint from '../../../components/Endpoint.astro';

<Endpoint method="POST" path="/api/developer/v1/contacts" title="Upsert one contact" />
<Endpoint method="POST" path="/api/developer/v1/contacts/bulk" title="Upsert up to 100 contacts" />
<Endpoint method="GET" path="/api/developer/v1/phone-numbers" title="List available phone numbers" />

`phone_number` is required. Optional contact fields include name, email, city, location, source, lead status, custom instruction, tags, and note.

```python
import os, requests

contact = requests.post(
    "https://api.vaniagent.com/api/developer/v1/contacts",
    headers={"X-API-Key": os.environ["VANIAGENT_API_KEY"]},
    json={
        "phone_number": "+919876543210",
        "contact_name": "Asha Rao",
        "source": "crm_webhook",
        "lead_status": "new",
        "tags": ["demo-request", "south-region"],
        "note": "Requested a product demo.",
    },
)
contact.raise_for_status()
```

Supported normalized sources and lead statuses are listed in **Contacts → Statuses, sources, and tags**. Upsert semantics help prevent duplicate application records, but callers should still normalize numbers consistently.