---
title: "Capture a signup"
method: POST
path: "/signups"
---

# Capture a signup

`POST /signups`

## Request

- Base URL: `https://api.hightouch.com/api/v1`
- URL: `https://api.hightouch.com/api/v1/signups`
- Auth: HTTP bearer

Record a signup: consent for a delivery handle, plus the fields the form
collected.

Whether consent settles immediately or waits for a double opt-in
confirmation is the channel's configuration, so one call covers both and
the response says which happened.

## Request body

- CreateSignupRequest
  - `traits` SignupTraitsRequest: A signup's own fields, as collected by the form. They are written to the customer's warehouse and never stored by Hightouch.
  - `optIn` 'single' | 'double': Force an opt-in style. Omit to let the topic and channel decide; a value they cannot honor is refused rather than silently resolved.
  - `source` string: Which form or landing page this signup came from.
  - `topicExternalIdentifier` string
  - `topicId` string: The subscription topic being consented to, by id or external identifier. Omit both to record consent for the channel itself.
  - `channel` 'email' | 'sms', required: Delivery channels a signup can consent on.
  - `handle` string, required: Email address or E.164 phone number, matching `channel`.

## Response `200`

Ok

- union
  - CreateSignupResponse: `subscribed` means consent settled in this request. `doi_pending_confirmation` means a confirmation was sent and consent settles when the person answers, which may be days later.
    - `status` 'subscribed' | 'doi_pending_confirmation', required
  - SignupErrorResponse
    - `message` string, required
    - `code` string, required

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `409`: Conflict
- `422`: Unprocessable
- `500`: Something went wrong
- `502`: Confirmation could not be sent

## Changes

- **2026-10-12** `08c348439a60`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/hightouch/apis/hightouch-api/changes/signups/post.md)

---

[API](https://skmtc.dev/hightouch/apis/hightouch-api.md) - [All operations](https://skmtc.dev/hightouch/apis/hightouch-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hightouch/apis/hightouch-api/revisions/7f9793951e4f?raw)