Skip to main content
POST
/
v1
/
prospects
Create a prospect
curl --request POST \
  --url https://api.slant.app/v1/prospects \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "book_id": "abc123xyz",
  "household_name": "The Smith Family",
  "first_name": "John",
  "last_name": "Doe",
  "preferred_name": "Johnny",
  "email": "john.doe@example.com",
  "phone_number": "5555551234",
  "date_of_birth": "1990-01-15",
  "job_title": "Software Engineer",
  "head_of_household": {
    "first_name": "John",
    "last_name": "Doe",
    "middle_name": "Robert",
    "preferred_name": "Johnny",
    "salutation": "Mr.",
    "suffix": "Jr.",
    "gender": "male",
    "designations": "CPA, CFP",
    "date_of_birth": "1990-01-15",
    "job_title": "Software Engineer",
    "email": "john.doe@example.com",
    "phone_number": "5555551234",
    "email_addresses": [
      {
        "email": "john@example.com",
        "email_type": "personal",
        "is_primary": true
      }
    ],
    "phone_numbers": [
      {
        "phone_number": "+15555551234",
        "phone_type": "mobile",
        "is_primary": true
      }
    ],
    "addresses": [
      {
        "line1": "123 Main St",
        "line2": "Apt 4B",
        "city": "New York",
        "state": "NY",
        "zip": "10001",
        "country_code": "US",
        "address_type": "home",
        "is_primary": true
      }
    ],
    "employments": [
      {
        "business_name": "Acme Corp",
        "role": "Software Engineer",
        "start_date": "2023-01-15",
        "end_date": "2024-12-31",
        "actively_employed": true
      }
    ],
    "custom_fields": {
      "risk_tolerance": "Moderate"
    }
  },
  "custom_fields": {
    "lead_source": "Referral"
  }
}
'
{
  "id": "abc123xyz",
  "type": "Client",
  "name": "The Smith Family",
  "book_id": "book123xyz",
  "people": [
    {
      "id": "abc123xyz",
      "book_id": "book123xyz",
      "first_name": "John",
      "last_name": "Doe",
      "household_id": "xyz789abc",
      "contact_id": "cnt456def",
      "role_type": "client",
      "middle_name": "Robert",
      "salutation": "Mr.",
      "suffix": "Jr.",
      "maiden_name": "Smith",
      "gender": "male",
      "designations": "CPA, CFP",
      "household_role": "head_of_household",
      "preferred_name": "Johnny",
      "date_of_birth": "1985-06-15",
      "job_title": "Software Engineer",
      "ssn": "***-**-6789",
      "drivers_license_number": "******7890",
      "email_addresses": [
        {
          "email": "john.doe@example.com",
          "email_type": "personal",
          "is_primary": true
        }
      ],
      "phone_numbers": [
        {
          "phone_number": "+15555551234",
          "phone_type": "mobile",
          "is_primary": true
        }
      ],
      "addresses": [
        {
          "address_type": "home",
          "is_primary": true,
          "line1": "123 Main St",
          "line2": "Apt 4B",
          "city": "New York",
          "state": "NY",
          "zip": "10001",
          "country_code": "US"
        }
      ],
      "employments": [
        {
          "business_name": "Acme Corp",
          "id": "emp123xyz",
          "person_id": "abc123xyz",
          "role": "Software Engineer",
          "start_date": "2023-01-15",
          "end_date": "2024-12-31",
          "actively_employed": true
        }
      ],
      "custom_fields": {
        "preferred_contact_method": "Email",
        "risk_tolerance": "Moderate"
      }
    }
  ],
  "tier": "Platinum",
  "became_client_at": "2024-01-01T00:00:00Z",
  "profile_picture_url": "https://api.example.com/v1/households/abc123xyz/avatar",
  "custom_fields": {
    "pageport_lead_source": "Landing Page",
    "industry": "Technology"
  }
}

Authorizations

​
Authorization
string
header
required

OAuth 2.0 Bearer Token from Clerk authentication

Headers

​
Idempotency-Key
string

Unique key to ensure idempotent request handling. If a request with the same key was already processed, the original response will be returned.

Body

application/json

Prospect data. At least one person name field (first_name, last_name, or preferred_name) is required. Contact methods (email, phone) are optional. Provide either head_of_household (advanced) or flat person fields (simple).

​
book_id
string
required

The book ID

Example:

"abc123xyz"

​
household_name
string

Name of the household

Example:

"The Smith Family"

​
first_name
string

Simple format: Head of household first name

Example:

"John"

​
last_name
string

Simple format: Head of household last name

Example:

"Doe"

​
preferred_name
string

Simple format: Preferred name

Example:

"Johnny"

​
email
string<email>

Simple format: Primary email address

Example:

"john.doe@example.com"

​
phone_number
string

Simple format: Primary phone number

Example:

"5555551234"

​
date_of_birth
string<date>

Simple format: Date of birth (YYYY-MM-DD)

Example:

"1990-01-15"

​
job_title
string

Simple format: Job title

Example:

"Software Engineer"

​
head_of_household
object

Advanced format: Full person schema with nested contacts. Takes priority over flat fields if provided.

​
custom_fields
object

Household custom field values as key-value pairs

Example:
{ "lead_source": "Referral" }

Response

prospect created

​
id
string
required

The ID of the household

Example:

"abc123xyz"

​
type
enum<string>
required

The type of household

Available options:
Client,
Prospect
Example:

"Client"

​
name
string
required

The name of the household

Example:

"The Smith Family"

​
book_id
string
required

The ID of the book this household belongs to

Example:

"book123xyz"

​
people
object[]
required

The people in this household

​
tier
string | null

The tier label for this household (null for Prospects)

Example:

"Platinum"

​
became_client_at
string<date-time> | null

When this household became a client (null for Prospects)

Example:

"2024-01-01T00:00:00Z"

​
profile_picture_url
string<uri> | null

URL to the household profile picture

Example:

"https://api.example.com/v1/households/abc123xyz/avatar"

​
custom_fields
object

Custom field values as key-value pairs

Example:
{
  "pageport_lead_source": "Landing Page",
  "industry": "Technology"
}