---
title: "Create contact"
method: POST
path: "/v1/contacts"
tags: ["Contacts"]
---

# Create contact

`POST /v1/contacts`

## Request

- Base URL: `https://api.forwardemail.net`
- URL: `https://api.forwardemail.net/v1/contacts`
- Auth: HTTP basic

Create a new contact. You can provide either vCard content directly or individual contact fields that will be converted to vCard format. If a contact with the same ID already exists, a conflict error will be returned.

## Request body

- ContactInput
  - `content` string: vCard content (if not provided, will be generated from other fields)
  - `full_name` string: Contact's full name
  - `contact_id` string: Custom contact ID (if not provided, will be auto-generated)
  - `uid` string: Contact UID (if not provided, will be auto-generated)
  - `emails` object[]: Array of email addresses
    - `value` string, email, required
    - `type` string
  - `phone_numbers` object[]: Array of phone numbers
    - `value` string, required
    - `type` string
  - `phones` object[]: Array of phone numbers (alias for phone_numbers)
    - `value` string, required
    - `type` string
  - `addresses` object[]: Array of addresses
    - `street` string
    - `city` string
    - `state` string
    - `postalCode` string
    - `country` string
    - `type` string
  - `is_group` boolean: Whether contact is a group

## Response `201`

Contact created successfully

- Contact
  - `id` string, required: Contact ID (contact_id from CardDAV)
  - `uid` string, required: Contact UID
  - `full_name` string, required: Contact's full name
  - `content` string, required: vCard content
  - `etag` string, required: ETag for versioning
  - `is_group` boolean, required: Whether contact is a group
  - `emails` object[], required: Array of email addresses
    - `value` string, email, required
    - `type` string
  - `phone_numbers` object[], required: Array of phone numbers
    - `value` string, required
    - `type` string
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `object` 'contact', required

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `409`: Conflict
- `500`: Internal Server Error

---

[API](https://skmtc.dev/forwardemail/apis/forward-email-api.md) · [All operations](https://skmtc.dev/forwardemail/apis/forward-email-api/llms.txt) · [OpenAPI document](https://skmtc.dev/forwardemail/apis/forward-email-api/revisions/ecefab4527f6?raw)