Contacts

Overview

Contacts represent people and companies you work with. They fall into two categories:

Owners: Property owners who receive rental income distributions
Vendors: Service providers who receive expense payments

Contacts are essential for:

Ownership periods - Assigning property ownership
Transactions - Recording payments and expenses
Owner statements - Generating financial reports
Tax reporting (1099s)

Key Concepts

Contact Types

Type	Description	Use For
`owner`	Property owners	Ownership periods, owner statements, payouts
`vendor`	Service providers	Expense payments, vendor bills

Company Types

Contacts can be individuals or business entities:

Company Type	Description
(none)	Individual person
`limited_liability_company`	LLC
`c_corporation`	C Corp
`s_corporation`	S Corp
`partnership`	Partnership
`trust_estate`	Trust or Estate

Company type affects tax reporting requirements (1099-MISC, 1099-NEC, etc.).

Contact Status

Status	Description
`active`	Contact is in use
`inactive`	Contact is disabled

Contact Information

Each contact can have:

Name: Display name (company or individual)
First name: For individuals
Email: Contact email address
Phone: Contact phone number
Address: Full mailing address

Payout Accounts

Owners can have a designated payout account (payoutAccountId) for receiving distributions. When creating transfers, this account is used for the payment.

Tax Information

For tax reporting purposes, contacts store:

Tax identifier: SSN or EIN (masked in responses for security)
Used for 1099 generation
Company type determines reporting requirements

External References

Field	Description
`uniqueRef`	Your internal contact ID for cross-referencing
`connectionId`	Link to PMS or external system
`source`	External system reference

Ownership Periods

The response includes listings where this contact is an owner:

ownershipPeriods: All historical ownership periods
activeOwnerships: Currently active ownership periods

Common Scenarios

Creating an Owner

POST /contacts
{
  "type": "owner",
  "name": "John Smith",
  "firstName": "John",
  "email": "john@example.com",
  "phone": "+1-555-123-4567",
  "companyType": null,
  "taxIdentifier": "123-45-6789",
  "address": {
    "street": "123 Main Street",
    "city": "Miami",
    "state": "FL",
    "zipCode": "33101",
    "country": "US"
  },
  "payoutAccountId": "account-owner-payout"
}

Creating a Vendor

POST /contacts
{
  "type": "vendor",
  "name": "ABC Cleaning Services",
  "companyType": "limited_liability_company",
  "email": "info@abccleaning.com",
  "phone": "+1-555-987-6543",
  "taxIdentifier": "12-3456789",
  "address": {
    "street": "456 Business Ave",
    "city": "Miami",
    "state": "FL",
    "zipCode": "33102",
    "country": "US"
  }
}

Creating an LLC Owner

POST /contacts
{
  "type": "owner",
  "name": "Smith Family Holdings LLC",
  "companyType": "limited_liability_company",
  "email": "admin@smithholdings.com",
  "taxIdentifier": "87-6543210"
}

Updating a Contact

PUT /contacts/contact-123
{
  "email": "newemail@example.com",
  "payoutAccountId": "account-new-payout"
}

API Endpoints

Method	Endpoint	Description
`GET`	`/contacts`	List contacts with filters
`GET`	`/contacts/{id}`	Get contact details
`POST`	`/contacts`	Create a new contact
`PUT`	`/contacts/{id}`	Update a contact
`DELETE`	`/contacts/{id}`	Delete a contact

Filtering Contacts

GET /contacts?type=owner&status=active
GET /contacts?type=vendor&connectionId=conn-123

Response Structure

{
  "id": "contact-123",
  "type": "owner",
  "status": "active",
  "name": "John Smith",
  "firstName": "John",
  "email": "john@example.com",
  "phone": "+1-555-123-4567",
  "companyType": null,
  "taxIdentifier": "***-**-6789",
  "uniqueRef": "OWNER-001",
  "payoutAccountId": "account-owner-payout",
  "address": {
    "street": "123 Main Street",
    "city": "Miami",
    "state": "FL",
    "zipCode": "33101",
    "country": "US"
  },
  "source": {
    "type": "hostaway",
    "id": "hostaway-owner-456"
  },
  "ownershipPeriods": [
    {
      "listingId": "listing-abc",
      "split": 100,
      "startAt": "2024-01-01",
      "endAt": null
    }
  ],
  "activeOwnerships": [
    {
      "listingId": "listing-abc",
      "split": 100,
      "startAt": "2024-01-01",
      "endAt": null
    }
  ]
}

Batch Operations

For syncing from external systems, contacts support batch upsert:

POST /contacts/batch
{
  "connectionId": "conn-pms-123",
  "data": [
    {
      "uniqueRef": "OWNER-001",
      "type": "owner",
      "name": "John Smith",
      "email": "john@example.com"
    },
    {
      "uniqueRef": "OWNER-002",
      "type": "owner",
      "name": "Jane Doe",
      "email": "jane@example.com"
    }
  ]
}

Ownership Periods - Connect owners to properties
Transactions - Payments to owners and vendors
Owner Statements - Financial reports for owners
Accounts - Payout accounts

Contacts

On this page