---
title: "Create Contact"
method: POST
path: "/print-mail/v1/contacts"
tags: ["Contacts"]
---

# Create Contact

`POST /print-mail/v1/contacts`

Creates a contact. This will also verify the contact's address **if you create it using a live API key**. To sucessfully create a contact, either a `firstName`, a `companyName`, or both are required. You can supply both, but you **cannot** supply neither.

You have the option to supply the entire address (except for `countryCode`) via `addressLine1`, in which case PostGrid will parse it automatically. However, this is **not guaranteed to be correct**, so we recommend passing along the structured address fields (`city`, `provinceOrState`, etc) if you have them.

_Note that if you create a contact that has identical information to another contact, this will simply update the description of the existing contact and return it. This avoids creating duplicate contacts._

## Request body

- union
  - ContactCreateWithFirstName
    - `addressLine1` string, required — The first line of the contact's address.
    - `addressLine2` string — Second line of the contact's address, if applicable.
    - `city` string — The city of the contact's address.
    - `provinceOrState` string — Province or state of the contact's address.
    - `postalOrZip` string — The postal or ZIP code of the contact's address.
    - `countryCode` string, required — The ISO 3611-1 country code of the contact's address.
    - `companyName` string — Company name of the contact.
    - `lastName` string — Last name of the contact.
    - `email` string — Email of the contact.
    - `phoneNumber` string — Phone number of the contact.
    - `jobTitle` string — Job title of the contact.
    - `skipVerification` boolean — If `true`, PostGrid will skip running this contact's address through our address verification system.
    - `forceVerifiedStatus` boolean — If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
    - `secret` boolean — If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.
    - `description` string — An optional string describing this resource. Will be visible in the API and the dashboard.
    - `metadata` object — See the section on Metadata.
    - `firstName` string, required
  - ContactCreateWithCompanyName
    - `addressLine1` string, required — The first line of the contact's address.
    - `addressLine2` string — Second line of the contact's address, if applicable.
    - `city` string — The city of the contact's address.
    - `provinceOrState` string — Province or state of the contact's address.
    - `postalOrZip` string — The postal or ZIP code of the contact's address.
    - `countryCode` string, required — The ISO 3611-1 country code of the contact's address.
    - `firstName` string — First name of the contact.
    - `lastName` string — Last name of the contact.
    - `email` string — Email of the contact.
    - `phoneNumber` string — Phone number of the contact.
    - `jobTitle` string — Job title of the contact.
    - `skipVerification` boolean — If `true`, PostGrid will skip running this contact's address through our address verification system.
    - `forceVerifiedStatus` boolean — If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
    - `secret` boolean — If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.
    - `description` string — An optional string describing this resource. Will be visible in the API and the dashboard.
    - `metadata` object — See the section on Metadata.
    - `companyName` string, required

## Response `201`

The request has succeeded and a new resource has been created as a result.

- Contact
  - `id` string, required — A unique ID prefixed with contact_
  - `description` string — An optional string describing this resource. Will be visible in the API and the dashboard.
  - `metadata` object — See the section on Metadata.
  - `live` boolean, required — `true` if this is a live mode resource else `false`.
  - `createdAt` string, date-time, required — The UTC time at which this resource was created.
  - `updatedAt` string, date-time, required — The UTC time at which this resource was last updated.

## Other responses

- `400` — The server could not understand the request due to invalid syntax.
- `401` — Access is unauthorized.
- `404` — The server cannot find the requested resource.
- `422` — Client error
- `429` — Client error
- `500` — Server error

---

[API](https://skmtc.net/postgrid/apis/postgrid-address-verification-api.md) · [All operations](https://skmtc.net/postgrid/apis/postgrid-address-verification-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/postgrid/postgrid-address-verification-api/revisions/537d2bbc624a/schema)