Create Intake Lead

curl --request POST \
  --url https://app.hipp.health/api/v1/intake-leads \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "client": {
    "firstName": "Jane",
    "lastName": "Doe",
    "birthdate": "2015-03-04"
  },
  "caregiver": {
    "firstName": "John",
    "lastName": "Doe",
    "relationship": "FATHER",
    "email": "john.doe@example.com",
    "phone": "+14155551234"
  }
}
'

{
  "client": {
    "publicId": "<string>"
  },
  "caregiver": {
    "publicId": "<string>"
  }
}

{
  "message": "Validation Error",
  "statusCode": 400,
  "validationErrors": [
    {
      "code": "invalid_type",
      "message": "Required",
      "path": [
        "email"
      ]
    }
  ]
}

{
  "error": "API key required",
  "statusCode": 401
}

{
  "error": "Access denied",
  "statusCode": 403
}

{
  "error": "A record with this email already exists",
  "statusCode": 409
}

{
  "error": "An unexpected error occurred",
  "statusCode": 500
}

POST

intake-leads

curl --request POST \
  --url https://app.hipp.health/api/v1/intake-leads \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "client": {
    "firstName": "Jane",
    "lastName": "Doe",
    "birthdate": "2015-03-04"
  },
  "caregiver": {
    "firstName": "John",
    "lastName": "Doe",
    "relationship": "FATHER",
    "email": "john.doe@example.com",
    "phone": "+14155551234"
  }
}
'

{
  "client": {
    "publicId": "<string>"
  },
  "caregiver": {
    "publicId": "<string>"
  }
}

{
  "message": "Validation Error",
  "statusCode": 400,
  "validationErrors": [
    {
      "code": "invalid_type",
      "message": "Required",
      "path": [
        "email"
      ]
    }
  ]
}

{
  "error": "API key required",
  "statusCode": 401
}

{
  "error": "Access denied",
  "statusCode": 403
}

{
  "error": "A record with this email already exists",
  "statusCode": 409
}

{
  "error": "An unexpected error occurred",
  "statusCode": 500
}

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

{
  "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).

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.

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

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.

Success Response (201)

{
  "client": { "publicId": "usr_1234567890_abc123def" },
  "caregiver": { "publicId": "usr_0987654321_xyz789ghi" }
}

Error Responses

400 - Validation Error

{
  "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):

{
  "error": "Unknown client.selectedLocations: loc_bad123",
  "statusCode": 400
}

401 - Unauthorized

{
  "error": "API key required",
  "statusCode": 401
}

401 - Invalid API Key

{
  "error": "Invalid API key",
  "statusCode": 401
}

403 - Forbidden

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

{
  "error": "Insufficient permissions for this action",
  "statusCode": 403
}

409 - Conflict

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

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

Examples

cURL Example

# 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

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);
}

Authorizations

Authorization

string

header

required

API key authentication. Include your API key in the Authorization header as 'Bearer '

Body

application/json

client

object

required

The draft patient to create.

Show child attributes

caregiver

object

required

The caregiver to create and attach to the lead.

Show child attributes

attribution

object

Optional marketing attribution captured upstream. Unknown keys are stripped.

Show child attributes

Response

Intake lead created successfully

client

object

required

Show child attributes

caregiver

object

required

Show child attributes

API Documentation

Endpoints

Create Intake Lead