> ## Documentation Index
> Fetch the complete documentation index at: https://help.privy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a contact

> Create a new contact. At least one of `email` or `phone_number` is required.

If a contact with the same email or phone number already exists, a `409 Conflict`
error is returned along with the `id` of the existing contact. Use the **Update a contact** endpoint to modify existing contacts.

If a previously deleted contact matches the provided email or phone number,
the contact is restored with the new data.

When `sms_consent` is `subscribed`, Privy automatically sends a TCPA-required
welcome SMS to the contact. Pass `send_welcome_sms: false` to suppress this
message if you have already collected consent outside of Privy.

**Required scope:** `contacts_write`




## OpenAPI

````yaml openapi/privy-api.yaml POST /contacts
openapi: 3.1.0
info:
  title: Privy API
  version: '1.0'
  description: |
    The Privy API lets you programmatically manage your contact list.
    Create, update, unsubscribe, and remove contacts — or retrieve your
    full contact list with filtering and pagination.
servers:
  - url: https://api.privy.com/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Account
    description: Retrieve information about the authenticated Privy account.
  - name: Contacts
    description: Manage your contact list.
  - name: Orders
    description: Report orders placed in your store.
  - name: Events
    description: Ingest custom events to trigger Flows and other automations.
paths:
  /contacts:
    post:
      tags:
        - Contacts
      summary: Create a contact
      description: >
        Create a new contact. At least one of `email` or `phone_number` is
        required.


        If a contact with the same email or phone number already exists, a `409
        Conflict`

        error is returned along with the `id` of the existing contact. Use the
        **Update a contact** endpoint to modify existing contacts.


        If a previously deleted contact matches the provided email or phone
        number,

        the contact is restored with the new data.


        When `sms_consent` is `subscribed`, Privy automatically sends a
        TCPA-required

        welcome SMS to the contact. Pass `send_welcome_sms: false` to suppress
        this

        message if you have already collected consent outside of Privy.


        **Required scope:** `contacts_write`
      operationId: createContact
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateContactRequest'
            example:
              email: jane@example.com
              first_name: Jane
              last_name: Doe
              tags:
                - new-contact
              email_consent: subscribed
      responses:
        '201':
          description: Contact created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Contact'
              example:
                data:
                  id: cus_x9y8z7w6v5u4t3s2
                  first_name: Jane
                  last_name: Doe
                  email: jane@example.com
                  email_consent: subscribed
                  phone_number: null
                  sms_consent: never_subscribed
                  tags:
                    - new-contact
                  custom_fields: {}
                  created_at: '2025-04-01T12:00:00Z'
                  updated_at: '2025-04-01T12:00:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/InsufficientScope'
        '409':
          description: >-
            A contact with this email or phone number already exists. The
            response includes the `id` of the existing contact.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                  id:
                    type: string
                    description: The ID of the existing contact that caused the conflict.
              example:
                error:
                  code: conflict
                  message: A contact with this email already exists
                id: cus_x9y8z7w6v5u4t3s2
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
      security:
        - bearerAuth: []
components:
  schemas:
    CreateContactRequest:
      type: object
      description: |
        At least one of `email` or `phone_number` is required.

        Use `email_consent` and `sms_consent` to set the contact's marketing
        consent status at creation time.
      properties:
        email:
          type: string
          format: email
          description: Contact's email address.
          example: jane@example.com
        phone_number:
          type: string
          description: Contact's phone number in E.164 format.
          example: '+15551234567'
        first_name:
          type: string
          description: Contact's first name.
          example: Jane
        last_name:
          type: string
          description: Contact's last name.
          example: Doe
        tags:
          type: array
          items:
            type: string
          description: Tags to apply to the contact.
          example:
            - vip
            - repeat-buyer
        custom_fields:
          type: object
          additionalProperties:
            type: string
          description: Flat key-value pairs. Nested objects are not allowed.
          example:
            loyalty_tier: gold
        email_consent:
          type: string
          enum:
            - subscribed
            - unsubscribed
            - never_subscribed
            - suppressed
          description: >
            Email marketing consent status. If not provided, defaults to
            `never_subscribed`.

            `compliance_suppressed` is read-only and cannot be set on create.
          example: subscribed
        sms_consent:
          type: string
          enum:
            - subscribed
            - unsubscribed
            - never_subscribed
            - single_opt_in
          description: >
            SMS marketing consent status. `pending` is read-only and cannot be
            set.

            `subscribed` and `single_opt_in` require a valid `phone_number` from
            a

            supported country. Cannot be `unsubscribed` for new contacts (no
            existing

            consent to revoke).
          example: never_subscribed
        send_welcome_sms:
          type: boolean
          default: true
          description: >
            When `sms_consent` is set to `subscribed` and the contact
            transitions

            to a confirmed SMS opt-in state, Privy sends a TCPA-required welcome

            SMS. Set to `false` to suppress this message when you have already

            collected consent outside of Privy.
          example: false
    Contact:
      type: object
      properties:
        id:
          type: string
          description: >-
            Stable, unique identifier for the contact. Use this value in
            `/v1/contacts/{id}` endpoints.
          example: cus_a1b2c3d4e5f6g7h8
        first_name:
          type: string
          example: Jane
        last_name:
          type: string
          example: Doe
        email:
          type: string
          format: email
          example: jane@example.com
        email_consent:
          type: string
          enum:
            - subscribed
            - unsubscribed
            - never_subscribed
            - suppressed
            - compliance_suppressed
          description: >
            Email marketing consent status.


            - `subscribed` — contact opted into email (explicit or implicit
            consent).

            - `unsubscribed` — contact opted out of email.

            - `never_subscribed` — no opt-in and no opt-out.

            - `suppressed` — merchant-suppressed (bounce list, manual action).

            - `compliance_suppressed` — system-suppressed (CAN-SPAM, abuse
            complaint). Read-only.
          example: subscribed
        phone_number:
          type: string
          example: '+15551234567'
        sms_consent:
          type: string
          enum:
            - subscribed
            - unsubscribed
            - never_subscribed
            - single_opt_in
            - pending
          description: >
            SMS marketing consent status.


            - `subscribed` — contact has confirmed SMS opt-in.

            - `unsubscribed` — contact opted out of SMS.

            - `never_subscribed` — no opt-in and no opt-out.

            - `single_opt_in` — merchant collected a single opt-in (not yet
            confirmed).

            - `pending` — Privy is awaiting a confirmation reply. Read-only.
          example: subscribed
        tags:
          type: array
          items:
            type: string
          example:
            - vip
            - repeat-buyer
        custom_fields:
          type: object
          additionalProperties:
            type: string
          example:
            loyalty_tier: gold
            referral_code: JANE2024
        created_at:
          type: string
          format: date-time
          example: '2025-01-15T10:30:00Z'
        updated_at:
          type: string
          format: date-time
          example: '2025-03-20T14:22:00Z'
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - invalid_client
                - invalid_scope
                - unauthorized
                - insufficient_scope
                - not_found
                - conflict
                - validation_failed
                - rate_limited
              example: validation_failed
            message:
              type: string
              example: One or more fields are invalid
            details:
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                    example: email
                  message:
                    type: string
                    example: is required
  responses:
    Unauthorized:
      description: Missing or invalid bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: unauthorized
              message: Bearer token is missing or invalid
    InsufficientScope:
      description: Token lacks the required scope for this endpoint.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: insufficient_scope
              message: Token does not have the required scope
    ValidationFailed:
      description: One or more fields failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: validation_failed
              message: One or more fields are invalid
              details:
                - field: email
                  message: is required
    RateLimited:
      description: Rate limit exceeded. Retry after the specified time.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
          example: 42
        X-RateLimit-Limit-Minute:
          description: Maximum requests allowed per minute.
          schema:
            type: integer
          example: 60
        X-RateLimit-Remaining-Minute:
          description: Requests remaining in the current minute window.
          schema:
            type: integer
          example: 0
        X-RateLimit-Reset-Minute:
          description: Unix timestamp when the minute window resets.
          schema:
            type: integer
          example: 1711929600
        X-RateLimit-Limit-Day:
          description: Maximum requests allowed per day.
          schema:
            type: integer
          example: 10000
        X-RateLimit-Remaining-Day:
          description: Requests remaining in the current day window.
          schema:
            type: integer
          example: 9500
        X-RateLimit-Reset-Day:
          description: Unix timestamp when the day window resets.
          schema:
            type: integer
          example: 1712016000
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: rate_limited
              message: Rate limit exceeded
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API token or OAuth access token
      description: >
        Send either an API token or an OAuth access token as

        `Authorization: Bearer <token>`. See the Authentication page for
        details.

````