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

# Create Intake Lead

> Creates a CRM draft lead (draft patient + caregiver) from an external system that can fire an authenticated request, such as a marketing form or CRM workflow. No invite email is sent to the caregiver created through this endpoint.

## Create Intake Lead

Creates a CRM draft lead (a draft patient plus one caregiver) from an external system, such as a marketing form, CRM workflow, or lead-gen integration. No invite email is sent to the caregiver created through this endpoint.

### Headers

```
Authorization: Bearer <your-api-key>
Content-Type: application/json
```

### Request Body

```json theme={null}
{
  "client": {
    "firstName": "Jane",
    "lastName": "Doe",
    "birthdate": "2015-03-04",
    "sex": "FEMALE",
    "address": "123 Main St",
    "city": "Springfield",
    "state": "IL",
    "zip": "62704",
    "country": "US",
    "timezone": "America/Chicago",
    "selectedLocations": ["loc_abc123"],
    "intakeStatusKey": "LEAD",
    "labelPublicIds": ["lbl_xyz789"]
  },
  "caregiver": {
    "firstName": "John",
    "lastName": "Doe",
    "relationship": "FATHER",
    "email": "john.doe@example.com",
    "phone": "+14155551234"
  },
  "attribution": {
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_campaign": "spring-intake",
    "gclid": "abc123"
  }
}
```

### Field Descriptions

**`client` (required)**

* `firstName` (required): Client's first name (minimum 2 characters)
* `lastName` (required): Client's last name (minimum 2 characters)
* `birthdate` (required): Date of birth in `YYYY-MM-DD` format. Cannot be in the future.
* `sex` (optional): One of `MALE`, `FEMALE`, `OTHER`
* `address`, `city`, `state`, `zip`, `country` (optional): Home address fields
* `timezone` (optional): A valid IANA timezone identifier (e.g. `America/Chicago`)
* `selectedLocations` (optional): Public IDs of clinic locations to attach to the lead. Each must belong to your organization, or the request is rejected with a `400` naming the unknown ID(s).
* `intakeStatusPublicId` (optional): A custom intake stage's public ID. Provide this or `intakeStatusKey`, not both — providing both is rejected with a `400`.
* `intakeStatusKey` (optional): A built-in stage key: `LEAD`, `WAITLIST`, `VERIFIED_BENEFITS`, `AUTH_REQUESTED`, `AUTH_APPROVED`, `ASSESSMENT_SCHEDULED`, `THERAPY_SCHEDULED`, `ACTIVE`, `INACTIVE`, `SERVICES_PAUSED`, `DISCHARGED`, `ARCHIVED`. Your organization must have a stage configured for the given key, or this returns a `400`.
* `labelPublicIds` (optional): Public IDs of intake labels to attach. Each must belong to your organization, or the request is rejected with a `400` naming the unknown ID(s).

<Note>
  When neither `intakeStatusPublicId` nor `intakeStatusKey` is provided, the lead is placed on your organization's first active pipeline stage (in board order) — the same placement a public intake form submission gets. If your organization has no active stages configured, the lead is created with no stage.
</Note>

**`caregiver` (required)**

* `firstName`, `lastName` (required): Caregiver's name (minimum 2 characters each)
* `relationship` (required): One of `MOTHER`, `STEPMOTHER`, `FATHER`, `STEPFATHER`, `GUARDIAN`, `GRANDPARENT`, `SIBLING`, `OTHER`, `UNKNOWN`
* `email` (required): A valid email address
* `phone` (required): A valid US phone number in E.164 format (e.g. `+14155551234`). The number is validated as a real, deliverable US number — placeholder/fictitious numbers are rejected.

**`attribution` (optional)**

Marketing attribution captured upstream. Unknown keys are stripped; all fields are optional strings.

* `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`
* `gclid`, `gbraid`, `wbraid`, `fbclid`
* `referrer`, `landingPage`

<Note>
  This data is normalized into a source/channel/campaign and stored on the lead so API-created leads feed the same CRM filtering and lead-source reporting as leads submitted through the in-app intake form.
</Note>

### Success Response (201)

```json theme={null}
{
  "client": { "publicId": "usr_1234567890_abc123def" },
  "caregiver": { "publicId": "usr_0987654321_xyz789ghi" }
}
```

### Error Responses

#### 400 - Validation Error

```json theme={null}
{
  "message": "Validation Error",
  "statusCode": 400,
  "validationErrors": [
    {
      "code": "invalid_enum_value",
      "path": ["caregiver", "relationship"],
      "message": "caregiver.relationship must be one of MOTHER, STEPMOTHER, FATHER, STEPFATHER, GUARDIAN, GRANDPARENT, SIBLING, OTHER, UNKNOWN"
    }
  ]
}
```

Unknown `selectedLocations`, `intakeStatusPublicId`, `intakeStatusKey`, or `labelPublicIds` are rejected as a plain error naming the offending value(s):

```json theme={null}
{
  "error": "Unknown client.selectedLocations: loc_bad123",
  "statusCode": 400
}
```

#### 401 - Unauthorized

```json theme={null}
{
  "error": "API key required",
  "statusCode": 401
}
```

#### 401 - Invalid API Key

```json theme={null}
{
  "error": "Invalid API key",
  "statusCode": 401
}
```

#### 403 - Forbidden

Returned when your API key's role does not have permission to create or edit patients.

```json theme={null}
{
  "error": "Insufficient permissions for this action",
  "statusCode": 403
}
```

#### 409 - Conflict

Returned when the caregiver's email already exists in your organization.

```json theme={null}
{
  "error": "Caregiver could not be created. Please review and retry the submission.",
  "statusCode": 409
}
```

## Examples

### cURL Example

```bash theme={null}
# Create an intake lead
curl -X POST https://app.hipp.health/api/v1/intake-leads \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "client": {
      "firstName": "Jane",
      "lastName": "Doe",
      "birthdate": "2015-03-04"
    },
    "caregiver": {
      "firstName": "John",
      "lastName": "Doe",
      "relationship": "FATHER",
      "email": "john.doe@example.com",
      "phone": "+14155551234"
    }
  }'
```

### JavaScript Example

```javascript theme={null}
const createIntakeLead = async (leadData) => {
  const response = await fetch("/api/v1/intake-leads", {
    method: "POST",
    headers: {
      Authorization: "Bearer your-api-key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify(leadData),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error ?? error.message);
  }

  return response.json();
};

// Usage
try {
  const result = await createIntakeLead({
    client: { firstName: "Jane", lastName: "Doe", birthdate: "2015-03-04" },
    caregiver: {
      firstName: "John",
      lastName: "Doe",
      relationship: "FATHER",
      email: "john.doe@example.com",
      phone: "+14155551234",
    },
  });
  console.log("Lead created:", result);
} catch (error) {
  console.error("Error creating lead:", error.message);
}
```


## OpenAPI

````yaml POST /v1/intake-leads
openapi: 3.0.0
info:
  title: Hipp Health API
  version: 1.0.0
  description: API for managing users and resources within your Hipp Health organization
servers:
  - url: https://app.hipp.health/api
    description: Production Server
security: []
paths:
  /v1/intake-leads:
    post:
      tags:
        - intake-leads
      summary: Create an intake lead
      description: >-
        Creates a CRM draft lead (draft patient + caregiver) from an external
        system that can fire an authenticated request, such as a marketing form
        or CRM workflow. No invite email is sent to the caregiver created
        through this endpoint.
      operationId: createIntakeLead
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateIntakeLeadRequest'
            examples:
              basic:
                summary: Minimal required fields
                value:
                  client:
                    firstName: Jane
                    lastName: Doe
                    birthdate: '2015-03-04'
                  caregiver:
                    firstName: John
                    lastName: Doe
                    relationship: FATHER
                    email: john.doe@example.com
                    phone: '+14155551234'
              complete:
                summary: With optional fields and attribution
                value:
                  client:
                    firstName: Jane
                    lastName: Doe
                    birthdate: '2015-03-04'
                    sex: FEMALE
                    city: Springfield
                    state: IL
                    zip: '62704'
                    timezone: America/Chicago
                    selectedLocations:
                      - loc_abc123
                    intakeStatusKey: LEAD
                    labelPublicIds:
                      - lbl_xyz789
                  caregiver:
                    firstName: John
                    lastName: Doe
                    relationship: FATHER
                    email: john.doe@example.com
                    phone: '+14155551234'
                  attribution:
                    utm_source: google
                    utm_medium: cpc
                    utm_campaign: spring-intake
                    gclid: abc123
      responses:
        '201':
          description: Intake lead created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateIntakeLeadResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '409':
          $ref: '#/components/responses/409'
        '500':
          $ref: '#/components/responses/500'
      security:
        - BearerAuth: []
components:
  schemas:
    CreateIntakeLeadRequest:
      type: object
      properties:
        client:
          $ref: '#/components/schemas/IntakeLeadClient'
        caregiver:
          $ref: '#/components/schemas/IntakeLeadCaregiver'
        attribution:
          $ref: '#/components/schemas/IntakeLeadAttribution'
      required:
        - client
        - caregiver
    CreateIntakeLeadResponse:
      type: object
      properties:
        client:
          type: object
          properties:
            publicId:
              type: string
              description: The created client's public ID.
          required:
            - publicId
        caregiver:
          type: object
          properties:
            publicId:
              type: string
              description: The created caregiver's public ID.
          required:
            - publicId
      required:
        - client
        - caregiver
    IntakeLeadClient:
      type: object
      description: The draft patient to create.
      properties:
        firstName:
          type: string
          minLength: 2
          description: Client's first name.
        lastName:
          type: string
          minLength: 2
          description: Client's last name.
        birthdate:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
          description: Date of birth (YYYY-MM-DD). Cannot be in the future.
          example: '2015-03-04'
        sex:
          $ref: '#/components/schemas/IntakeLeadSex'
        address:
          type: string
          description: Street address.
        city:
          type: string
        state:
          type: string
        zip:
          type: string
        country:
          type: string
        timezone:
          type: string
          description: IANA timezone identifier.
          example: America/Chicago
        selectedLocations:
          type: array
          items:
            type: string
          description: >-
            Public IDs of clinic locations to attach to the lead. Each must
            belong to your organization; an unknown ID returns a 400.
        intakeStatusPublicId:
          type: string
          description: >-
            A custom PatientStatus public ID. Provide this or intakeStatusKey,
            not both.
        intakeStatusKey:
          $ref: '#/components/schemas/IntakeStatusKey'
        labelPublicIds:
          type: array
          items:
            type: string
          description: >-
            Public IDs of intake labels to attach. Each must belong to your
            organization; an unknown ID returns a 400.
      required:
        - firstName
        - lastName
        - birthdate
    IntakeLeadCaregiver:
      type: object
      description: The caregiver to create and attach to the lead.
      properties:
        firstName:
          type: string
          minLength: 2
        lastName:
          type: string
          minLength: 2
        relationship:
          $ref: '#/components/schemas/Relationship'
        email:
          type: string
          format: email
        phone:
          type: string
          description: A valid, deliverable US phone number in E.164 format.
          example: '+14155551234'
      required:
        - firstName
        - lastName
        - relationship
        - email
        - phone
    IntakeLeadAttribution:
      type: object
      description: >-
        Optional marketing attribution captured upstream. Unknown keys are
        stripped.
      properties:
        utm_source:
          type: string
        utm_medium:
          type: string
        utm_campaign:
          type: string
        utm_term:
          type: string
        utm_content:
          type: string
        gclid:
          type: string
        gbraid:
          type: string
        wbraid:
          type: string
        fbclid:
          type: string
        referrer:
          type: string
        landingPage:
          type: string
    ValidationError:
      type: object
      required:
        - message
        - statusCode
        - validationErrors
      properties:
        message:
          type: string
          example: Validation Error
        statusCode:
          type: integer
          example: 400
        validationErrors:
          type: array
          description: Zod validation issues
          items:
            type: object
            properties:
              code:
                type: string
                example: invalid_type
              message:
                type: string
                example: Required
              path:
                type: array
                items:
                  oneOf:
                    - type: string
                    - type: integer
                example:
                  - email
    ApiErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message
          example: User not found
        statusCode:
          type: integer
          example: 404
      required:
        - error
        - statusCode
    IntakeLeadSex:
      type: string
      enum:
        - MALE
        - FEMALE
        - OTHER
      description: Client's sex.
    IntakeStatusKey:
      type: string
      enum:
        - LEAD
        - WAITLIST
        - VERIFIED_BENEFITS
        - AUTH_REQUESTED
        - AUTH_APPROVED
        - ASSESSMENT_SCHEDULED
        - THERAPY_SCHEDULED
        - ACTIVE
        - INACTIVE
        - SERVICES_PAUSED
        - DISCHARGED
        - ARCHIVED
      description: >-
        Built-in pipeline stage key. Your organization must have a stage
        configured for the given key, or the request returns a 400.
    Relationship:
      type: string
      enum:
        - MOTHER
        - STEPMOTHER
        - FATHER
        - STEPFATHER
        - GUARDIAN
        - GRANDPARENT
        - SIBLING
        - OTHER
        - UNKNOWN
      description: Caregiver's relationship to the client.
  responses:
    '400':
      description: Bad Request - Validation Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationError'
    '401':
      description: Unauthorized - API key required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
          example:
            error: API key required
            statusCode: 401
    '403':
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
          example:
            error: Access denied
            statusCode: 403
    '409':
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
          example:
            error: A record with this email already exists
            statusCode: 409
    '500':
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
          example:
            error: An unexpected error occurred
            statusCode: 500
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        API key authentication. Include your API key in the Authorization header
        as 'Bearer <your-api-key>'

````