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

# Create a contact

`POST /contacts`

Creates a contact for the authenticated account, or returns the existing active contact if one already exists for the given email. Optionally adds the contact to a list and registers an external system identifier. Both `source_identifier` and `system` must be provided together to create an external identifier.

## Request body

- ContactCreateBody
  - `email` string, email, required
  - `first_name` string
  - `last_name` string
  - `source` string — Origin of the contact (e.g. 'hubspot', 'csv')
  - `can_email` boolean — Sets the contact's emailability. Applied whether this POST creates a new contact or matches an existing active contact by email. Defaults to true on creation when omitted.
  - `list_id` integer — Add the contact to this list immediately
  - `subscriptions` ContactCreateSubscriptionItem[] — Optional subscriptions to create for the contact. Each entry upserts a canonical subscription (no integration) on (contact_id, subscription_type_id): if one already exists its can_email is updated rather than a duplicate being inserted.
    - `subscription_type_id` integer, required
    - `can_email` boolean — Whether this subscription is emailable. Accepts 0/1 or true/false.
  - `options` object — Arbitrary key-value attributes stored on the contact. Persisted only when this POST creates a new contact; ignored when an active contact already exists for the email (same as first_name/last_name/source). Use PUT /contacts/{id} to merge options into an existing contact.
  - `system` string — External system name (e.g. 'hubspot'). Must be provided together with `identifier` to create an external identifier record.
  - `identifier` string — The contact's ID in the external system. Must be provided together with `system`.
  - `system_identifier` string — Optional sub-system identifier (e.g. a HubSpot portal ID).

## Response `201`

Contact created (or existing contact returned)

## Other responses

- `400` — Bad request — email is required
- `401` — Unauthorized

---

[API](https://skmtc.net/rasa/apis/rasa-io-api.md) · [All operations](https://skmtc.net/rasa/apis/rasa-io-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/rasa/rasa-io-api/revisions/60891bc551db/schema)