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

# Create a prospect

> Creates a new prospect household with head of household information



## OpenAPI

````yaml /api-reference/openapi.yaml post /v1/prospects
openapi: 3.0.1
info:
  title: Slant Public API V1
  version: v1
  description: Public API for creating and managing resources in Slant
  contact:
    name: Slant API Support
    email: api@slant.com
servers:
  - url: https://api.slant.app
security:
  - bearer: []
paths:
  /v1/prospects:
    post:
      tags:
        - Prospects
      summary: Create a prospect
      description: Creates a new prospect household with head of household information
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
          description: >-
            Unique key to ensure idempotent request handling. If a request with
            the same key was already processed, the original response will be
            returned.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - book_id
              description: >-
                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).
              properties:
                book_id:
                  type: string
                  description: The book ID
                  example: abc123xyz
                household_name:
                  type: string
                  description: Name of the household
                  example: The Smith Family
                first_name:
                  type: string
                  description: 'Simple format: Head of household first name'
                  example: John
                last_name:
                  type: string
                  description: 'Simple format: Head of household last name'
                  example: Doe
                preferred_name:
                  type: string
                  description: 'Simple format: Preferred name'
                  example: Johnny
                email:
                  type: string
                  format: email
                  description: 'Simple format: Primary email address'
                  example: john.doe@example.com
                phone_number:
                  type: string
                  description: 'Simple format: Primary phone number'
                  example: '5555551234'
                phone_extension:
                  type: string
                  description: >-
                    Simple format: Optional phone extension for the primary
                    phone number
                  example: '1234'
                date_of_birth:
                  type: string
                  format: date
                  description: 'Simple format: Date of birth (YYYY-MM-DD)'
                  example: '1990-01-15'
                job_title:
                  type: string
                  description: 'Simple format: Job title'
                  example: Software Engineer
                head_of_household:
                  type: object
                  description: >-
                    Advanced format: Full person schema with nested contacts.
                    Takes priority over flat fields if provided.
                  properties:
                    first_name:
                      type: string
                      example: John
                    last_name:
                      type: string
                      example: Doe
                    middle_name:
                      type: string
                      example: Robert
                    preferred_name:
                      type: string
                      example: Johnny
                    salutation:
                      type: string
                      example: Mr.
                    suffix:
                      type: string
                      example: Jr.
                    gender:
                      type: string
                      enum:
                        - female
                        - male
                        - nonbinary
                        - other
                        - prefer_not_to_say
                      example: male
                    designations:
                      type: string
                      example: CPA, CFP
                    date_of_birth:
                      type: string
                      format: date
                      example: '1990-01-15'
                      description: Date of birth (YYYY-MM-DD)
                    job_title:
                      type: string
                      example: Software Engineer
                      description: Job title
                    email:
                      type: string
                      format: email
                      example: john.doe@example.com
                      description: 'Simple: single email as string'
                    phone_number:
                      type: string
                      example: '5555551234'
                      description: 'Simple: single phone as string'
                    phone_extension:
                      type: string
                      example: '1234'
                      description: 'Simple: extension for the single phone'
                    email_addresses:
                      type: array
                      description: 'Advanced: array of email objects with types'
                      items:
                        type: object
                        properties:
                          email:
                            type: string
                            format: email
                            example: john@example.com
                          email_type:
                            type: string
                            enum:
                              - personal
                              - business
                              - school
                              - other
                            example: personal
                          is_primary:
                            type: boolean
                            example: true
                    phone_numbers:
                      type: array
                      description: 'Advanced: array of phone objects with types'
                      items:
                        type: object
                        properties:
                          phone_number:
                            type: string
                            example: '+15555551234'
                          extension:
                            type: string
                            example: '1234'
                          phone_type:
                            type: string
                            enum:
                              - mobile
                              - work
                              - home
                              - fax
                              - other
                            example: mobile
                          is_primary:
                            type: boolean
                            example: true
                    addresses:
                      type: array
                      description: Array of addresses
                      items:
                        type: object
                        properties:
                          line1:
                            type: string
                            example: 123 Main St
                          line2:
                            type: string
                            example: Apt 4B
                          city:
                            type: string
                            example: New York
                          state:
                            type: string
                            example: NY
                          zip:
                            type: string
                            example: '10001'
                          country_code:
                            type: string
                            example: US
                          address_type:
                            type: string
                            enum:
                              - home
                              - work
                              - mailing
                              - other
                            example: home
                          is_primary:
                            type: boolean
                            example: true
                    employments:
                      type: array
                      description: Array of employment records
                      items:
                        type: object
                        properties:
                          business_name:
                            type: string
                            example: Acme Corp
                          role:
                            type: string
                            example: Software Engineer
                          start_date:
                            type: string
                            format: date
                            example: '2023-01-15'
                          end_date:
                            type: string
                            format: date
                            example: '2024-12-31'
                          actively_employed:
                            type: boolean
                            example: true
                    custom_fields:
                      type: object
                      description: Person custom field values as key-value pairs
                      example:
                        risk_tolerance: Moderate
                custom_fields:
                  type: object
                  description: Household custom field values as key-value pairs
                  example:
                    lead_source: Referral
        required: true
      responses:
        '201':
          description: prospect created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prospect'
        '400':
          description: bad request - invalid JSON
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                  - detail
                properties:
                  error:
                    type: string
                    description: Error code
                    enum:
                      - invalid_json
                  detail:
                    oneOf:
                      - type: string
                        description: Human-readable error description
                      - type: array
                        items:
                          type: string
                        description: Array of validation error messages
        '401':
          description: unauthorized - missing or invalid token
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                  - detail
                properties:
                  error:
                    type: string
                    description: Error code
                    enum:
                      - token_missing
                      - token_invalid
                  detail:
                    oneOf:
                      - type: string
                        description: Human-readable error description
                      - type: array
                        items:
                          type: string
                        description: Array of validation error messages
        '403':
          description: forbidden
        '422':
          description: unprocessable entity - invalid payload
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                  - detail
                properties:
                  error:
                    type: string
                    description: Error code
                    enum:
                      - invalid_payload
                      - record_invalid
                      - parameter_missing
                  detail:
                    oneOf:
                      - type: string
                        description: Human-readable error description
                      - type: array
                        items:
                          type: string
                        description: Array of validation error messages
      security:
        - bearer: []
components:
  schemas:
    Prospect:
      allOf:
        - $ref: '#/components/schemas/Household'
    Household:
      type: object
      required:
        - id
        - type
        - name
        - book_id
        - people
      properties:
        id:
          type: string
          description: The ID of the household
          example: abc123xyz
        type:
          type: string
          enum:
            - Client
            - Prospect
          description: The type of household
          example: Client
        name:
          type: string
          description: The name of the household
          example: The Smith Family
        tier:
          type: string
          description: The tier label for this household (null for Prospects)
          example: Platinum
          nullable: true
        became_client_at:
          type: string
          format: date-time
          description: When this household became a client (null for Prospects)
          example: '2024-01-01T00:00:00Z'
          nullable: true
        book_id:
          type: string
          description: The ID of the book this household belongs to
          example: book123xyz
        profile_picture_url:
          type: string
          format: uri
          description: URL to the household profile picture
          example: https://api.example.com/v1/households/abc123xyz/avatar
          nullable: true
        custom_fields:
          type: object
          description: Custom field values as key-value pairs
          example:
            pageport_lead_source: Landing Page
            industry: Technology
        people:
          type: array
          items:
            $ref: '#/components/schemas/Person'
          description: The people in this household
    Person:
      type: object
      required:
        - id
        - book_id
        - first_name
        - last_name
      properties:
        id:
          type: string
          description: The person ID
          example: abc123xyz
        book_id:
          type: string
          description: The book ID
          example: book123xyz
        household_id:
          type: string
          description: The household ID
          example: xyz789abc
          nullable: true
        contact_id:
          type: string
          description: The contact ID (present when person belongs to a contact)
          example: cnt456def
          nullable: true
        role_type:
          type: string
          enum:
            - client
            - prospect
            - contact
            - past_client
          description: The entity type this person belongs to
          example: client
          nullable: true
        first_name:
          type: string
          example: John
        middle_name:
          type: string
          example: Robert
          nullable: true
        last_name:
          type: string
          example: Doe
        salutation:
          type: string
          example: Mr.
          nullable: true
        suffix:
          type: string
          example: Jr.
          nullable: true
        maiden_name:
          type: string
          example: Smith
          nullable: true
        gender:
          type: string
          enum:
            - female
            - male
            - nonbinary
            - other
            - prefer_not_to_say
          example: male
          nullable: true
        designations:
          type: string
          example: CPA, CFP
          nullable: true
        household_role:
          type: string
          enum:
            - head_of_household
            - partner
            - spouse
            - dependent_child
            - other_adult
            - other_dependent
            - unknown
            - deceased
            - non_dependent_child
            - grandchild
          example: head_of_household
          nullable: true
          description: Only present when person belongs to a household
        preferred_name:
          type: string
          example: Johnny
          nullable: true
        date_of_birth:
          type: string
          format: date
          description: Date of birth
          example: '1985-06-15'
          nullable: true
        job_title:
          type: string
          description: Job title
          example: Software Engineer
          nullable: true
        ssn:
          type: string
          description: Obfuscated social security number
          example: '***-**-6789'
          nullable: true
        drivers_license_number:
          type: string
          description: Obfuscated driver's license number
          example: '******7890'
          nullable: true
        email_addresses:
          type: array
          items:
            $ref: '#/components/schemas/Email'
          description: Array of email addresses with primary designation
        phone_numbers:
          type: array
          items:
            $ref: '#/components/schemas/PhoneNumber'
          description: Array of phone numbers with primary designation
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/Address'
          description: Array of addresses with primary designation
        employments:
          type: array
          items:
            $ref: '#/components/schemas/Employment'
          description: Array of employment records
        custom_fields:
          type: object
          description: Custom field values as key-value pairs
          example:
            preferred_contact_method: Email
            risk_tolerance: Moderate
    Email:
      type: object
      required:
        - email
        - email_type
        - is_primary
      properties:
        email:
          type: string
          format: email
          example: john.doe@example.com
        email_type:
          type: string
          enum:
            - personal
            - business
            - school
            - other
          example: personal
        is_primary:
          type: boolean
          example: true
    PhoneNumber:
      type: object
      required:
        - phone_number
        - phone_type
        - is_primary
      properties:
        phone_number:
          type: string
          example: '+15555551234'
        extension:
          type: string
          nullable: true
          example: '1234'
        phone_type:
          type: string
          enum:
            - mobile
            - work
            - home
            - fax
            - other
          example: mobile
        is_primary:
          type: boolean
          example: true
    Address:
      type: object
      required:
        - address_type
        - is_primary
      properties:
        line1:
          type: string
          example: 123 Main St
          nullable: true
        line2:
          type: string
          example: Apt 4B
          nullable: true
        city:
          type: string
          example: New York
          nullable: true
        state:
          type: string
          example: NY
          nullable: true
        zip:
          type: string
          example: '10001'
          nullable: true
        country_code:
          type: string
          example: US
          nullable: true
        address_type:
          type: string
          enum:
            - home
            - work
            - mailing
            - other
          example: home
        is_primary:
          type: boolean
          example: true
    Employment:
      type: object
      required:
        - business_name
      properties:
        id:
          type: string
          description: The employment ID
          example: emp123xyz
        person_id:
          type: string
          description: The person ID
          example: abc123xyz
        business_name:
          type: string
          example: Acme Corp
        role:
          type: string
          example: Software Engineer
          nullable: true
        start_date:
          type: string
          format: date
          example: '2023-01-15'
          nullable: true
        end_date:
          type: string
          format: date
          example: '2024-12-31'
          nullable: true
        actively_employed:
          type: boolean
          example: true
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: OAuth
      description: OAuth 2.0 Bearer Token from Clerk authentication

````