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

# Create contact

`POST /contacts`

Creates a new contact record. The contact is assigned to the user associated with your API key. Related entity IDs use prefixed string IDs (for example `clt_`, `cs_`, `usr_`, `tag_`). Tag with `tags` (`tag_` prefix). Custom field values use `cf_*` keys — see the [Custom fields](/api-v2/custom-fields) guide.

## Request body

- ContactInput
  - `firstName` string, required — Contact first name
  - `lastName` string — Contact last name
  - `salutation` string — Title (Mr., Mrs., Dr., etc.)
  - `email` string, email, nullable — Email address
  - `phone` string — Phone number with country code
  - `jobTitle` string — Job title or position
  - `companyId` string — ID of the parent company to link this contact to
  - `stageId` string — Client stage ID
  - `leadStageId` string — Lead stage ID
  - `ownerUserId` string — Owner user ID
  - `vendorId` string — Vendor ID
  - `sourceId` string — CRM source ID
  - `tags` string[] — Tag IDs (tag_ prefix). Replaces the full set when provided.
  - `billingAddress` BillingAddressInput
    - `city` string, nullable — City
    - `address` string, nullable — Street address
    - `landmark` string, nullable — Nearby landmark
    - `state` string, nullable — State or province
    - `country` string, nullable — Country code, ISO3 code, or country name
    - `postalCode` string, nullable — Postal code or ZIP code

## Response `200`

OK

- Contact
  - `id` string, required — Contact person's ID (clt_ prefix)
  - `name` string, required — Display name
  - `number` string, required — Auto-generated contact number
  - `type` 'contact' | 'company', nullable — Record type (always contact for this endpoint)
  - `firstName` string, required — First name
  - `lastName` string, nullable — Last name
  - `email` string, nullable — Email address
  - `phone` string, nullable — Phone number
  - `salutation` string, nullable — Salutation
  - `jobTitle` string, nullable — Job title
  - `description` string, nullable — Description
  - `taxNumber` string, nullable — Tax number
  - `website` string, nullable — Website URL
  - `companyId` string, nullable — Parent company ID
  - `companyName` string, nullable — Parent company name
  - `parentClientId` string, nullable — Parent client ID (same as companyId for contacts)
  - `stageId` string, nullable — Client stage ID
  - `stageName` string, nullable — Client stage label
  - `leadStageId` string, nullable — Lead stage ID
  - `ownerUserId` string, nullable — Owner user ID
  - `crmSourceId` string, nullable — CRM source ID
  - `sourceName` string, nullable — CRM source name
  - `currency` string, nullable — Currency code
  - `openingBalance` number, required — Opening balance
  - `showJobAmountToWorker` boolean, required — Whether job amounts are visible to field workers
  - `isClientPortalEnabled` boolean, required — Whether the client portal is enabled
  - `internalNotes` string, nullable — Internal notes
  - `profileImage` string, nullable — Profile image URL
  - `instagram` string, nullable — Instagram handle or URL
  - `facebook` string, nullable — Facebook handle or URL
  - `linkedin` string, nullable — LinkedIn handle or URL
  - `twitter` string, nullable — Twitter handle or URL
  - `createdAt` string, date-time — When the contact was created
  - `updatedAt` string, date-time — When the contact was last updated

## Other responses

- `400` — Validation error or bad request
- `401` — Missing or invalid API key
- `403` — Insufficient permission
- `404` — Resource not found
- `429` — Rate limit exceeded

---

[API](https://skmtc.net/heffl/apis/heffl-api-v2-beta.md) · [All operations](https://skmtc.net/heffl/apis/heffl-api-v2-beta/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/heffl/heffl-api-v2-beta/versions/27006cfef4d8/schema)