API docs by Redocly

Homebase360 API (1.2.0)

Download OpenAPI specification:

Homebase360 Support: support@homebase360.io URL: https://homebase360.io

API for integration with Homebase360 customer and job management system

Health Check

Test API authentication

Simple endpoint to verify API key authentication is working correctly. Returns basic information about the authenticated business account.

Authorizations:
ApiKeyAuth

Responses

Request samples 

curl -X GET "https://us-central1-homebase-360.cloudfunctions.net/api/v1/ping" \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json"

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Customers

Get customers

Retrieves customer information based on search criteria. Multiple search parameters can be combined and will return customers matching ANY of the provided criteria (logical OR). If no criteria is provided, returns empty array.

Authorizations:
ApiKeyAuth
query Parameters
customerId
string
Example: customerId=Ekk9AvDeDihAEU8CMT0W

Specific customer ID to look for

phone
string
Example: phone=+13031234567

Customer's mobile phone number (E.164 format, e.g. +13038284444)

email
string
Example: email=john.smith@example.com

Customer's email address

identifiers
string
Example: identifiers=abc123,+13038284444,john@example.com

Comma-separated list of customer IDs, phone numbers, or email addresses (max 100 identifiers)

limit
integer <= 100
Default: 25
Example: limit=50

Maximum number of results to return (max 100, default 25)

Responses

Request samples 

curl -X GET "https://us-central1-homebase-360.cloudfunctions.net/api/v1/customers?customerId=Ekk9AvDeDihAEU8CMT0W" \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json"

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ]
}

Create a new customer

Creates a new customer with the provided information. Requires at least firstName or lastName, and at least one contact method (phone or email).

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
firstName
string

Customer's first name

lastName
string

Customer's last name

object (Phone)

All phone numbers must be in E.164 format (e.g. +13038284444)

email
Array of strings

List of email addresses (max 2). Can also provide as comma or semicolon-separated string.

address
Array of strings

List of physical addresses (max 2). Can also provide as semicolon or asterisk-separated string.

notes
string
Default: ""

Additional notes about the customer

tags
Array of strings

Tags for categorization. Can also provide as comma, semicolon, or asterisk-separated string.

notifications
boolean
Default: true

Whether the customer should receive notifications

Responses

Request samples

Content type
application/json
{
  • "firstName": "John",
  • "lastName": "Smith",
  • "phone": {
    },
  • "email": [
    ],
  • "address": [
    ],
  • "notes": "Prefers afternoon appointments",
  • "tags": [
    ],
  • "notifications": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Update an existing customer

Updates an existing customer's information

Authorizations:
ApiKeyAuth
path Parameters
customerId
required
string

ID of the customer to update

Request Body schema: application/json
required
firstName
string

Customer's first name

lastName
string

Customer's last name

object (Phone)

All phone numbers must be in E.164 format (e.g. +13038284444)

email
Array of strings

List of email addresses

address
Array of strings

List of physical addresses

notes
string

Additional notes about the customer

tags
Array of strings

Tags for categorization

notifications
boolean

Whether the customer should receive notifications

Responses

Request samples

Content type
application/json
{
  • "firstName": "John",
  • "lastName": "Smith Updated",
  • "phone": {
    },
  • "notes": "Updated notes",
  • "notifications": false
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Jobs

Get jobs/schedule

Retrieves jobs based on search criteria. If no criteria provided, returns the current day's jobs.

Authorizations:
ApiKeyAuth
query Parameters
jobId
string

Specific job ID to look for

startDate
string <date-time>

Start date in ISO 8601 format (e.g. "2023-05-15T00:00:00Z") - jobs starting on/after this date

endDate
string <date-time>

End date in ISO 8601 format (e.g. "2023-05-15T23:59:59Z") - jobs starting on/before this date

limit
integer <= 100
Default: 50

Maximum number of results to return (max 100)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ]
}

Create a new job

Creates a new job associated with a customer

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
customerId
required
string

Customer ID (must exist in your account)

start
required
string <date-time>

Start date and time in ISO 8601 format

end
required
string <date-time>

End date and time in ISO 8601 format (must be after start)

required
Array of objects (LineItem) non-empty

List of items/services for the job (minimum 1 item required)

note
string
Default: ""

Note for the job (optional)

LeadSource (string) or object

Lead source information (optional). Accepts string format or legacy object format for backwards compatibility

Responses

Request samples

Content type
application/json
{
  • "customerId": "Ekk9AvDeDihAEU8CMT0W",
  • "start": "2023-05-15T14:30:00Z",
  • "end": "2023-05-15T16:30:00Z",
  • "lineItems": [
    ],
  • "note": "Please call customer before arrival"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Update an existing job

Updates an existing job's information

Authorizations:
ApiKeyAuth
path Parameters
jobId
required
string

ID of the job to update

Request Body schema: application/json
required
start
string <date-time>

New start date and time in ISO 8601 format

end
string <date-time>

New end date and time in ISO 8601 format

note
string

New note for the job

Responses

Request samples

Content type
application/json
{
  • "start": "2023-05-15T15:00:00Z",
  • "end": "2023-05-15T17:00:00Z",
  • "note": "Customer requested a later time"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Leads

Get leads

Retrieves leads based on search criteria. Returns non-archived leads matching the provided filters.

Authorizations:
ApiKeyAuth
query Parameters
leadId
string

Fetch a specific lead by ID

customerId
string

Fetch all leads for a specific customer

status
string
Enum: "new" "first_contact" "second_contact" "third_contact" "on_hold"

Filter by lead status

limit
integer <= 100
Default: 25

Maximum number of results to return

Responses

Request samples 

curl -X GET "https://us-central1-homebase-360.cloudfunctions.net/api/v1/leads?status=new&limit=10" \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json"

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ]
}

Create a new lead

Creates a new lead with smart customer lookup/creation. This intelligent endpoint handles three scenarios:

Scenario 1: Existing Customer by ID Provide the customerId field to create a lead for an existing customer. Returns 404 if customer not found.

Scenario 2: Phone-based Lookup/Merge Provide customer details including phone.mobile. The API will:

  • Search for an existing customer with that mobile phone number
  • If found: Merge new data with existing customer, update customer record, create lead
  • If not found: Create new customer, create lead

Scenario 3: New Customer Provide customer details without customerId or phone.mobile. The API will:

  • Always create a new customer
  • Create lead for the new customer

You can either provide a customerId, or a name and a contact method: firstName/lastName and any-phone/email.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
customerId
string

Method 1: Existing customer ID

firstName
string

Method 2: Customer's first name (at least firstName or lastName required if using customer details)

lastName
string

Method 2: Customer's last name (at least firstName or lastName required if using customer details)

object (Phone)

All phone numbers must be in E.164 format (e.g. +13038284444)

email
Array of strings

Method 2: List of email addresses

address
Array of strings

Method 2: List of physical addresses

notes
string

Method 2: Additional notes about the customer

tags
Array of strings

Method 2: Tags for categorization

notifications
boolean

Method 2: Whether customer should receive notifications

Array of objects (LineItem)

Array of line items (optional for leads)

note
string

Note about the lead

leadSource
string (LeadSource)

Source of the lead. Use "Online" for online sources, "Direct" for direct contact/referrals, or provide a custom source name (e.g., "Facebook Ad", "Google Ads", "Referral Partner"). Custom sources will be automatically created and associated with your business.

status
string
Default: "new"
Enum: "new" "first_contact" "second_contact" "third_contact" "on_hold"

Initial status of the lead

assignedTo
Array of strings

Array of employee IDs to assign the lead to

Responses

Request samples

Content type
application/json
Example
{
  • "customerId": "Ekk9AvDeDihAEU8CMT0W",
  • "lineItems": [
    ],
  • "note": "Customer interested in monthly service",
  • "leadSource": "Online",
  • "status": "new"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Update an existing lead

Updates an existing lead's information. Only non-archived leads can be updated.

Authorizations:
ApiKeyAuth
path Parameters
leadId
required
string

ID of the lead to update

Request Body schema: application/json
required
status
string
Enum: "new" "first_contact" "second_contact" "third_contact" "on_hold"

Updated lead status

note
string

Updated note for the lead

Array of objects (LineItem)

Replacement array of line items

assignedTo
Array of strings

Replacement array of employee IDs

leadSource
string (LeadSource)

Source of the lead. Use "Online" for online sources, "Direct" for direct contact/referrals, or provide a custom source name (e.g., "Facebook Ad", "Google Ads", "Referral Partner"). Custom sources will be automatically created and associated with your business.

Responses

Request samples

Content type
application/json
{
  • "status": "first_contact",
  • "note": "Called customer, discussed options. Following up next week."
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Messages

Send an SMS/MMS message

Sends an SMS or MMS message to a customer's mobile phone. Requires an active Enterprise subscription. Subject to daily rate limits (500 SMS/day).

Provide either mobilePhone or customerId (or both):

  • mobilePhone: must be the phone.mobile of an existing customer
  • customerId: customer must have a valid phone.mobile on file
  • Both: mobilePhone must match the customer's phone.mobile
Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
mobilePhone
string

Customer's mobile phone in E.164 format. Must belong to an existing customer.

customerId
string

Customer ID. Customer must have a mobile phone on file.

message
string <= 200 characters

Message text. Max 200 characters. Required if no mediaUrl.

mediaUrl
string <uri>

HTTPS URL of media to send as MMS. Required if no message.

Responses

Request samples

Content type
application/json
Example
{
  • "mobilePhone": "+13031234444",
  • "message": "Your appointment is confirmed for tomorrow at 2pm"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get messaging stats and limits

Returns the current messaging usage stats and daily rate limits for the business.

Authorizations:
ApiKeyAuth

Responses

Request samples 

curl -X GET "https://us-central1-homebase-360.cloudfunctions.net/api/v1/messages/stats" \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json"

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}