---
title: "Create Contact"
method: POST
path: "/v1/agents/{agent_id}/contacts"
tags: ["Contacts"]
---

# Create Contact

`POST /v1/agents/{agent_id}/contacts`

## Request

- Base URL: `https://api.agentline.cloud`
- URL: `https://api.agentline.cloud/v1/agents/{agent_id}/contacts`
- Auth: HTTP bearer

Save a contact to an agent's contact list.

Each agent has its own contact list. Store who someone is (name), why the
agent deals with them (label, e.g. "dentist", "landlord", "customer") and
their phone number in E.164 format. Use list_contacts to look a number up
before a call, or to find who an inbound caller is.

A phone number can appear once per agent; saving it again returns HTTP 409
with the existing contact_id, so update that contact instead.

## Path parameters

- `agent_id` string, required: ID (agt_...) of the agent whose contact list to use, from create_agent or list_agents.

## Request body

- ContactCreate
  - `name` string, required: Who this is, e.g. 'Dr. Patel' or 'Joe's Plumbing'
  - `phone_number` string, required: The contact's phone number with a leading + and country code, e.g. '+12125551234'. Spaces, dashes, dots and parentheses are removed before saving; a number without a country code is rejected.
  - `label` string, nullable: Why the agent deals with this person, e.g. 'dentist', 'landlord', 'customer', 'Mom'. list_contacts can filter by it. Omit for no label.

## Response `200`

Successful Response

- ContactOut
  - `id` string, required: Unique contact identifier (e.g. 'con_abc123')
  - `agent_id` string, required: Agent whose contact list this entry belongs to
  - `name` string, required: Contact name
  - `label` string, nullable: Purpose or relationship
  - `phone_number` string, required: Phone number in E.164 format
  - `created_at` string, date-time, required: When the contact was saved
  - `updated_at` string, date-time, required: When the contact was last changed

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/agentline/apis/agentline-prepaid-phone-service-for-ai-agents.md) · [All operations](https://skmtc.dev/agentline/apis/agentline-prepaid-phone-service-for-ai-agents/llms.txt) · [OpenAPI document](https://skmtc.dev/agentline/apis/agentline-prepaid-phone-service-for-ai-agents/revisions/18c0bdbb4b30?raw)