---
title: "Create a new intake form"
method: POST
path: "/intake_forms"
tags: ["IntakeForms"]
---

# Create a new intake form

`POST /intake_forms`

Creates a new intake form in the HealthSherpa system. The intake form will be associated with the authenticated agent. All intake forms must have at least one of: first name, last name, email, or phone_number. This endpoint also supports creating nested resources for household income and members.
Optional `prescriptions` and `providers` fields may be included on the request. These values are **not** stored on the intake form record or in persisted `intake_info`. They are used only to populate the public **shop** (plan shopping) deeplink returned as `shopping_url` when the agent is eligible for deeplinking. They do not affect `client_apply_url` or any other persisted fields.

## Request body

- IntakeFormWrite
  - `user_uploaded_note_content` string, nullable — Agent note for the client
  - `first_name` string, nullable — First name of the client. At least one of first_name, last_name, email, or phone_number is required.
  - `last_name` string, nullable — Last name of the client. At least one of first_name, last_name, email, or phone_number is required.
  - `external_id` string, nullable — An external reference or integration id for this intake (optional).
  - `email` string, email, nullable — Email address of the client. At least one of first_name, last_name, email, or phone_number is required.
  - `phone_number` string, nullable — Phone number of the client. At least one of first_name, last_name, email, or phone_number is required.
  - `someone_has_employer_coverage` boolean, nullable — Whether a member has employer coverage
  - `address` string, nullable — Street address
  - `address_2` string, nullable — Apartment or secondary address line
  - `city` string, nullable — City name
  - `state` string, nullable — USPS state abbreviation such as AZ and FL
  - `zip` string, nullable — ZIP or postal code
  - `projected_income_members` object[], nullable — List of household members with projected income
    - `name` string, nullable
    - `employer` string, nullable
    - `amount` number, nullable
  - `tax_household_members` object[], nullable — Include everyone who needs health insurance: the primary applicant, their spouse, and/or their dependents. If you do not specify the relationship, we'll assume that the first member is the primary, the second member is the spouse, and all other members are dependents.
    - `name` string, nullable
    - `date_of_birth` string, date, nullable
    - `sex` string, nullable — Must be one of male, female, or x
    - `relationship` string, nullable — Must be one of primary, dependent, or spouse
    - `uses_tobacco` boolean, nullable
  - `dry_run` boolean, nullable — Whether the API call should commit the requested changes. If dry_run is set to true, you'll get the same response body as if the intake form was created or edited. We will not actually persist the data.
  - `providers` union[], nullable — Provider NPI values appended to the shopping deeplink only. Not stored on the intake record.
    - union
      - string
      - number
  - `prescriptions` PrescriptionDeeplinkInput[], nullable — Prescription rows appended to the shopping deeplink only. Not stored on the intake record.
    - `id` string, required — Drug or prescription identifier used in the shop flow.
    - `duration` string, required — Drug duration in months. Use 12 if not known
    - `applicant_index` string, required — Index of applicant in Tax Household Members that the drug is for. Use 0 if irrelevant
    - `rx_norm_identifier` string, required — RX Norm Record identifier. This is the rx_norm_identifier field that's returned from the prescription API

## Response `201`

Intake form created successfully.

- IntakeFormResponse
  - `user_uploaded_note_content` string, nullable — Agent note for the client
  - `first_name` string, nullable — First name of the client. At least one of first_name, last_name, email, or phone_number is required.
  - `last_name` string, nullable — Last name of the client. At least one of first_name, last_name, email, or phone_number is required.
  - `external_id` string, nullable — An external reference or integration id for this intake (optional).
  - `email` string, email, nullable — Email address of the client. At least one of first_name, last_name, email, or phone_number is required.
  - `phone_number` string, nullable — Phone number of the client. At least one of first_name, last_name, email, or phone_number is required.
  - `someone_has_employer_coverage` boolean, nullable — Whether a member has employer coverage
  - `address` string, nullable — Street address
  - `address_2` string, nullable — Apartment or secondary address line
  - `city` string, nullable — City name
  - `state` string, nullable — USPS state abbreviation such as AZ and FL
  - `zip` string, nullable — ZIP or postal code
  - `projected_income_members` object[], nullable — List of household members with projected income
    - `name` string, nullable
    - `employer` string, nullable
    - `amount` number, nullable
  - `tax_household_members` object[], nullable — Include everyone who needs health insurance: the primary applicant, their spouse, and/or their dependents. If you do not specify the relationship, we'll assume that the first member is the primary, the second member is the spouse, and all other members are dependents.
    - `name` string, nullable
    - `date_of_birth` string, date, nullable
    - `sex` string, nullable — Must be one of male, female, or x
    - `relationship` string, nullable — Must be one of primary, dependent, or spouse
    - `uses_tobacco` boolean, nullable
  - `dry_run` boolean, nullable — Whether the API call should commit the requested changes. If dry_run is set to true, you'll get the same response body as if the intake form was created or edited. We will not actually persist the data.
  - `id` integer, required — The unique IntakeForm identifier
  - `shopping_url` string, uri, nullable — Deeplink to the quoter with prefilled data according to the intake form. Null if the agent is not eligible for deeplinking. Agent must be associated with a deeplink-enabled agency to be eligible. Please reach out to HealthSherpa for deeplink access. When the create or update request included optional `prescriptions` and/or `providers`, those values are reflected only here (shop query parameters); they are not persisted on the intake form.
  - `client_apply_url` string, uri, nullable — Deeplink to the application page with prefilled data according to the intake form. Null if agent is not eligible for deeplinking. Agent must be associated with a deeplink-enabled agency to be eligible. Please reach out to HealthSherpa for deeplink access.

## Other responses

- `400` — Missing or malformed parameter
- `401` — Unauthorized - Invalid, missing, or expired OAuth token
- `404` — Agent not found for the authenticated user
- `422` — The request was well-formed but could not be processed
- `429` — Rate limit reached. This API allows up to 100 requests per minute per client IP and up to 100 requests per minute per OAuth access token. Retry after the indicated interval.

---

[API](https://skmtc.net/healthsherpa/apis/health-insurance-quotes-api.md) · [All operations](https://skmtc.net/healthsherpa/apis/health-insurance-quotes-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/healthsherpa/health-insurance-quotes-api/revisions/3cbfff4e5929/schema)