> For the complete documentation index, see [llms.txt](https://docs.healthsherpa.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.healthsherpa.com/on-exchange-api-documentation/api-reference/intake-form-api/intake-forms.md).
# Intake Forms
## Create a new intake form
> 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.
```json
{"openapi":"3.0.3","info":{"title":"HealthSherpa Intake Form API","version":"1.0.0"},"servers":[{"url":"https://healthsherpa.com/external","description":"Production environment"},{"url":"https://staging.healthsherpa.com/external","description":"Staging environment"}],"security":[{"OAuth2":["intake_form_api"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication","flows":{"authorizationCode":{"authorizationUrl":"https://healthsherpa.com/oauth/authorize","tokenUrl":"https://healthsherpa.com/oauth/token","scopes":{"intake_form_api":"authorizes access to intake form api"}}}}},"schemas":{"IntakeFormResponse":{"allOf":[{"$ref":"#/components/schemas/BasicIntakeForm"},{"type":"object","required":["id"],"properties":{"id":{"type":"integer","description":"The unique IntakeForm identifier"},"shopping_url":{"type":"string","nullable":true,"format":"uri","description":"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.\n"},"client_apply_url":{"type":"string","nullable":true,"format":"uri","description":"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."}}}]},"BasicIntakeForm":{"type":"object","properties":{"user_uploaded_note_content":{"type":"string","nullable":true,"description":"Agent note for the client"},"first_name":{"type":"string","nullable":true,"description":"First name of the client. At least one of first_name, last_name, email, or phone_number is required."},"last_name":{"type":"string","nullable":true,"description":"Last name of the client. At least one of first_name, last_name, email, or phone_number is required."},"external_id":{"type":"string","nullable":true,"description":"An external reference or integration id for this intake (optional)."},"email":{"type":"string","format":"email","nullable":true,"description":"Email address of the client. At least one of first_name, last_name, email, or phone_number is required."},"phone_number":{"type":"string","nullable":true,"description":"Phone number of the client. At least one of first_name, last_name, email, or phone_number is required."},"someone_has_employer_coverage":{"type":"boolean","nullable":true,"description":"Whether a member has employer coverage"},"address":{"type":"string","nullable":true,"description":"Street address"},"address_2":{"type":"string","nullable":true,"description":"Apartment or secondary address line"},"city":{"type":"string","nullable":true,"description":"City name"},"state":{"type":"string","nullable":true,"description":"USPS state abbreviation such as AZ and FL"},"zip":{"type":"string","nullable":true,"description":"ZIP or postal code"},"projected_income_members":{"type":"array","nullable":true,"description":"List of household members with projected income","items":{"type":"object","properties":{"name":{"type":"string","nullable":true},"employer":{"type":"string","nullable":true},"amount":{"type":"number","nullable":true}}}},"tax_household_members":{"type":"array","nullable":true,"description":"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.\n","items":{"type":"object","properties":{"name":{"type":"string","nullable":true},"date_of_birth":{"type":"string","format":"date","nullable":true},"sex":{"type":"string","nullable":true,"description":"Must be one of male, female, or x"},"relationship":{"type":"string","nullable":true,"description":"Must be one of primary, dependent, or spouse"},"uses_tobacco":{"type":"boolean","nullable":true}}}},"dry_run":{"type":"boolean","nullable":true,"description":"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."}}},"Error":{"type":"object","required":["message","code"],"properties":{"message":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Machine-readable error code","enum":["invalid_access_token","expired_access_token","bad_request","internal_server_error","not_found","validation_error"]},"details":{"type":"array","description":"Detailed validation errors","items":{"type":"string"}}}},"RateLimitError":{"type":"object","required":["message","error","retry_after"],"properties":{"message":{"type":"string","description":"Human-readable explanation of the throttle."},"error":{"type":"string","description":"Machine-readable error type for rate limiting.","enum":["rate_limit_exceeded"]},"retry_after":{"type":"integer","description":"Suggested wait time in seconds before sending more traffic."}}},"IntakeFormWrite":{"allOf":[{"$ref":"#/components/schemas/BasicIntakeForm"},{"$ref":"#/components/schemas/IntakeFormShoppingDeeplinkParams"}]},"IntakeFormShoppingDeeplinkParams":{"type":"object","properties":{"providers":{"type":"array","nullable":true,"description":"Provider NPI values appended to the shopping deeplink only. Not stored on the intake record.\n","items":{"oneOf":[{"type":"string"},{"type":"number"}]}},"prescriptions":{"type":"array","nullable":true,"description":"Prescription rows appended to the shopping deeplink only. Not stored on the intake record.\n","items":{"$ref":"#/components/schemas/PrescriptionDeeplinkInput"}}}},"PrescriptionDeeplinkInput":{"type":"object","required":["id","duration","applicant_index","rx_norm_identifier"],"description":"A single prescription row used only for the shopping deeplink.\n","properties":{"id":{"type":"string","description":"Drug or prescription identifier used in the shop flow."},"duration":{"type":"string","description":"Drug duration in months. Use 12 if not known"},"applicant_index":{"type":"string","description":"Index of applicant in Tax Household Members that the drug is for. Use 0 if irrelevant"},"rx_norm_identifier":{"type":"string","description":"RX Norm Record identifier. This is the rx_norm_identifier field that's returned from the prescription API"}}}},"responses":{"BadRequest":{"description":"Missing or malformed parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Unauthorized - Invalid, missing, or expired OAuth token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"AgentNotFound":{"description":"Agent not found for the authenticated user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnprocessableEntity":{"description":"The request was well-formed but could not be processed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"TooManyRequests":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}}},"paths":{"/intake_forms":{"post":{"summary":"Create a new intake form","description":"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.\nOptional `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.\n","operationId":"createIntakeForm","tags":["IntakeForms"],"responses":{"201":{"description":"Intake form created successfully. ","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntakeFormResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/AgentNotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntakeFormWrite"}}}}}}}}
```
## Update an existing intake form
> Updates an existing intake form in the HealthSherpa system. The authenticated agent must be associated with the intake form. All intake forms must have at least one of: first name, last name, email, or phone\_number after update.\
> Optional \`prescriptions\` and \`providers\` fields may be included on the request. These values are \*\*not\*\* persisted on the intake form or merged into stored \`intake\_info\`. They are used only to add prescription, provider, and related shop query parameters to the \*\*shopping\*\* deeplink returned as \`shopping\_url\` when the agent is eligible for deeplinking. They do not affect \`client\_apply\_url\`.
```json
{"openapi":"3.0.3","info":{"title":"HealthSherpa Intake Form API","version":"1.0.0"},"servers":[{"url":"https://healthsherpa.com/external","description":"Production environment"},{"url":"https://staging.healthsherpa.com/external","description":"Staging environment"}],"security":[{"OAuth2":["intake_form_api"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication","flows":{"authorizationCode":{"authorizationUrl":"https://healthsherpa.com/oauth/authorize","tokenUrl":"https://healthsherpa.com/oauth/token","scopes":{"intake_form_api":"authorizes access to intake form api"}}}}},"schemas":{"IntakeFormResponse":{"allOf":[{"$ref":"#/components/schemas/BasicIntakeForm"},{"type":"object","required":["id"],"properties":{"id":{"type":"integer","description":"The unique IntakeForm identifier"},"shopping_url":{"type":"string","nullable":true,"format":"uri","description":"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.\n"},"client_apply_url":{"type":"string","nullable":true,"format":"uri","description":"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."}}}]},"BasicIntakeForm":{"type":"object","properties":{"user_uploaded_note_content":{"type":"string","nullable":true,"description":"Agent note for the client"},"first_name":{"type":"string","nullable":true,"description":"First name of the client. At least one of first_name, last_name, email, or phone_number is required."},"last_name":{"type":"string","nullable":true,"description":"Last name of the client. At least one of first_name, last_name, email, or phone_number is required."},"external_id":{"type":"string","nullable":true,"description":"An external reference or integration id for this intake (optional)."},"email":{"type":"string","format":"email","nullable":true,"description":"Email address of the client. At least one of first_name, last_name, email, or phone_number is required."},"phone_number":{"type":"string","nullable":true,"description":"Phone number of the client. At least one of first_name, last_name, email, or phone_number is required."},"someone_has_employer_coverage":{"type":"boolean","nullable":true,"description":"Whether a member has employer coverage"},"address":{"type":"string","nullable":true,"description":"Street address"},"address_2":{"type":"string","nullable":true,"description":"Apartment or secondary address line"},"city":{"type":"string","nullable":true,"description":"City name"},"state":{"type":"string","nullable":true,"description":"USPS state abbreviation such as AZ and FL"},"zip":{"type":"string","nullable":true,"description":"ZIP or postal code"},"projected_income_members":{"type":"array","nullable":true,"description":"List of household members with projected income","items":{"type":"object","properties":{"name":{"type":"string","nullable":true},"employer":{"type":"string","nullable":true},"amount":{"type":"number","nullable":true}}}},"tax_household_members":{"type":"array","nullable":true,"description":"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.\n","items":{"type":"object","properties":{"name":{"type":"string","nullable":true},"date_of_birth":{"type":"string","format":"date","nullable":true},"sex":{"type":"string","nullable":true,"description":"Must be one of male, female, or x"},"relationship":{"type":"string","nullable":true,"description":"Must be one of primary, dependent, or spouse"},"uses_tobacco":{"type":"boolean","nullable":true}}}},"dry_run":{"type":"boolean","nullable":true,"description":"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."}}},"Error":{"type":"object","required":["message","code"],"properties":{"message":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Machine-readable error code","enum":["invalid_access_token","expired_access_token","bad_request","internal_server_error","not_found","validation_error"]},"details":{"type":"array","description":"Detailed validation errors","items":{"type":"string"}}}},"RateLimitError":{"type":"object","required":["message","error","retry_after"],"properties":{"message":{"type":"string","description":"Human-readable explanation of the throttle."},"error":{"type":"string","description":"Machine-readable error type for rate limiting.","enum":["rate_limit_exceeded"]},"retry_after":{"type":"integer","description":"Suggested wait time in seconds before sending more traffic."}}},"IntakeFormWrite":{"allOf":[{"$ref":"#/components/schemas/BasicIntakeForm"},{"$ref":"#/components/schemas/IntakeFormShoppingDeeplinkParams"}]},"IntakeFormShoppingDeeplinkParams":{"type":"object","properties":{"providers":{"type":"array","nullable":true,"description":"Provider NPI values appended to the shopping deeplink only. Not stored on the intake record.\n","items":{"oneOf":[{"type":"string"},{"type":"number"}]}},"prescriptions":{"type":"array","nullable":true,"description":"Prescription rows appended to the shopping deeplink only. Not stored on the intake record.\n","items":{"$ref":"#/components/schemas/PrescriptionDeeplinkInput"}}}},"PrescriptionDeeplinkInput":{"type":"object","required":["id","duration","applicant_index","rx_norm_identifier"],"description":"A single prescription row used only for the shopping deeplink.\n","properties":{"id":{"type":"string","description":"Drug or prescription identifier used in the shop flow."},"duration":{"type":"string","description":"Drug duration in months. Use 12 if not known"},"applicant_index":{"type":"string","description":"Index of applicant in Tax Household Members that the drug is for. Use 0 if irrelevant"},"rx_norm_identifier":{"type":"string","description":"RX Norm Record identifier. This is the rx_norm_identifier field that's returned from the prescription API"}}}},"responses":{"BadRequest":{"description":"Missing or malformed parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Unauthorized - Invalid, missing, or expired OAuth token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFoundError":{"description":"Intake Form associated with the authenticated agent cannot be found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnprocessableEntity":{"description":"The request was well-formed but could not be processed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"TooManyRequests":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}}},"paths":{"/intake_forms/{id}":{"patch":{"summary":"Update an existing intake form","description":"Updates an existing intake form in the HealthSherpa system. The authenticated agent must be associated with the intake form. All intake forms must have at least one of: first name, last name, email, or phone_number after update.\nOptional `prescriptions` and `providers` fields may be included on the request. These values are **not** persisted on the intake form or merged into stored `intake_info`. They are used only to add prescription, provider, and related shop query parameters to the **shopping** deeplink returned as `shopping_url` when the agent is eligible for deeplinking. They do not affect `client_apply_url`.\n","operationId":"updateIntakeForm","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","format":"int64"},"description":"HealthSherpa intake form id returned from create and update responses."}],"tags":["IntakeForms"],"responses":{"200":{"description":"Intake form updated successfully. ","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntakeFormResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFoundError"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntakeFormWrite"}}}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.healthsherpa.com/on-exchange-api-documentation/api-reference/intake-form-api/intake-forms.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.