Higharc API

Interested in using the Higharc API? Reach out to our Customer Success or Sales teams to inquire about enabling it for your account.

Developer Portal

Once the API is enabled on your account, you’ll have a “Developer Portal” menu item in your account’s Dashboard —

From here, you can create API tokens and test our endpoints using the built-in interactive documentation. Available endpoints are all documented and kept up-to-date here.

Concepts

Studio Documents

Studio documents are stored in a .home file format and can be loaded and edited in the Higharc product called Studio. These documents model a home, are configured via their attached options, and can be used to export construction documents.

Master Plans

A Master Plan is a published Studio file and it lives in your Plan Library. This Master Plan drives the base configuration for a model.

Locations

Locations can be Divisions, Communities or Phases and are used to organize geographic data and lots lists and create a hierarchy that defines inheritance of certain properties.

Location Plans

A Location Plan is an instance of a Master Plan at a particular Location.

Lots

Every Location can have a list of lots which can also correspond to a Lot map. Those lots can be made available to particular Location Plans. These Lots can have prices (premiums), garage handing and be designated as Model or Spec.

Lot Location Plans

This is the intersection of a Location Plan and Lot, allowing for additional configuration for a particular model on a particular lot.

Options

Options are choices that are available for a home. At Higharc we organize them into Option Sets which are how these Options are grouped for selection. One example of an Option Set is a garage that may be sold in three different configurations, from which one can be chosen.

Home Plans

A Home Plan is an instance of a Location Plan that can be configured by a homebuyer.

A Home Plan can have one or more Contracts, each representing a prospective or closed buyer (also known in some systems as a quote/priceout). On a standard lot there's typically one contract per Home Plan; on spec/model lots, a builder can pre-configure a single Home Plan and let multiple prospective buyers each open their own contract against it before one closes. Customer, sales agent, and pricing-override data live on the Contract, not the Home Plan — see the Webhooks guide for the contracts payload shape.

Option Templates

Option Templates allow for the control of pricing, base/default, and availability of options.

Plan Inheritance

Option data originates at the Master Plan level and flows downstream through a hierarchy of plans—Location Plans, Lot Plans, and finally Home Plans. Each layer inherits data from the one before it, but can also override it.

Master Plan → Location Plan → Lot Plan → Home Plan

Considerations

Note: Higharc previously only supported one Location type, “Community”. Because of this you may see legacy properties like communityId where the value is a Location ID or communityPlanId where the value is a Location Plan ID. This work is in progress and we apologize for any confusion it creates in the meantime.

Authenticating

An Authorization header with a valid JWT token is required for all requests. To get a token, follow the instructions below.

Retrieving a JWT token

To get a token, send a request to the following endpoint.

Endpoint

POST /api/v1/public/token

This request should contain an Authorization header containing your Base64-encoded Client App ID and secret, prefixed with "Basic". Example:

Authorization: Basic eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

To properly encode your Client App ID and secret, separate the two keys with a colon, then Base64-encode the result. A pseudo-code example:

// Pass the "header" string to the Authorization header in your POST request
var encodedToken = base64(clientAppId + ":" + clientAppSecret);
var header = "Basic " + encodedToken;

The result of this POST request will be a token in an RFC 6749-compatible format.

Using the JWT token

Pass your token along to all authenticated requests in the Authorization header, prefixed with "Bearer". Example:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Basic Setup

This section will go through the basic setup of plans, options and lots. There are some important places where we can attach External IDs to Higharc objects, allowing us to map them to external systems.

Master Plans

After they have been created, add External IDs to Master Plans. This can be done by going to Plan Library > Edit Plan Details in Higharc.

We can list all master plans with the following endpoint.

Endpoint

GET /api/v1/builders/{builderId}/master-plans

Tip: Use this response to map each internal id to its corresponding externalId, connecting Higharc’s data with your system.

Locations

To manually add External IDs to Locations you can go to Locations > Edit (Division|Community|Phase) Details in Higharc.

Alternatively we can handle this during creation via the API.

Endpoint

POST /api/v1/builders/{builderId}/locations

Include an externalId property in the request body
The masterPlanIds should include the list of plans offered at this location
If setting up a location hierarchy, use parentId
Use allowHomePlans to control whether home plans are permitted at this location. Defaults to true for communities, phases, and multi-units; false otherwise. The API will reject attempts to disable home plans at a location where they already exist.

We can list all locations with the following endpoint.

Endpoint

GET /api/v1/builders/{builderId}/locations

Tip: Use this response to map each internal id to its corresponding externalId, connecting Higharc’s data with your system.

Location Plans

To manually add External IDs to Location Plans you can go to Locations > Location Plans > Edit Plan Details in Higharc.

Alternatively we can handle this during creation via the API.

Endpoint

POST /api/v1/builders/{builderId}/locations/{locationId}/location-plans

Include an externalId property in the request body
The masterPlanId from which this plan is based is required
If setting up a location hierarchy, use parentId

We can list all location plans with the following endpoint.

Endpoint

GET /api/v1/builders/{builderId}/locations

Tip: Use this response to map each internal id to its corresponding externalId, connecting Higharc’s data with your system.

Lots

We can manually create lots by navigating to Locations > Lots, adding them one at a time or using the CSV upload tool. Using either method, or when dealing with existing lots, make sure to provide External IDs.

Alternatively we can create Lots via the API.

Endpoint

POST /api/v1/builders/{builderId}/lots

Include an externalId property in the request body
The locationId to which this lot belongs is required

We can list all lots with the following endpoint.

Endpoint

GET /api/v1/builders/{builderId}/lots

This endpoint can be filtered by locationIds and locationPlanIds, and is paginated.

Tip: Use this response to map each internal id to its corresponding externalId, connecting Higharc’s data with your system.

Options

Option and Option Set creation occurs in Studio. They can be connected to data in your system with the following properties.

Option Sets	Options
`builderOptionSetCode`	`builderOptionCode`

Home Plans

We can manually create home plans by navigating to Locations > Add > Home Plan and provide an External ID at the time of creation.

Alternatively we can create Home Plans via the API.

Endpoint

POST /api/v1/builders/{builderId}/home-plans

Include an externalId property in the request body
The Location Plan for this home must be identified with communityPlanId

We can list all the home plans in a location with the following endpoint.

Endpoint

GET /api/v1/builders/{builderId}/home-plans

Tip: Use this response to map each internal id to its corresponding externalId, connecting Higharc’s data with your system.

Rate Limits

To ensure service stability for all users of the Higharc platform, the API enforces rate limits per client app using a points-based window (default: 100 requests per 60 seconds).

To monitor usage, check each API response for these headers:

Header	Description
`X-RateLimit-Limit`	The maximum number of requests allowed in the current window
`X-RateLimit-Remaining`	The number of requests remaining in the current window
`Retry-After`	Returned with a `429` response — indicates when to retry

If the limit is exceeded, the API returns HTTP 429 Too Many Requests. When X-RateLimit-Remaining is getting low, reduce request frequency or implement backoff logic.

Workflows

Note: Many of the examples below use partial request or response data.

Setting Plan Option Data

We can control pricing, base/default, and availability of options at the Master Plan, Location Plan or Lot Location Plan using the Option Templates API.

Endpoint

PUT /api/v1/builders/{builderId}/option-templates/upsert

Targeting a Plan

We can select a particular plan by providing one of the following three values.

{
  "masterPlanId": "string",
  "communityPlanId": "string",
  "lotCommunityPlanId": "string",
}

Targeting an Option

We can then author updates in bulk to particular Option Sets or Options.

{
  "optionSets": [
    {
      "identifier": {
        "builderOptionSetCode": "string",
      },
      // Option set properties
    },
    // Additional option sets
  ],
}

{
  "options": [
    {
      "identifier": {
        "builderOptionCode": "string",
      },
      // Option properties
    },
    // Additional options
  ],
}

{
  "optionSets": [
    {
      "identifier": {
        "builderOptionSetCode": "string",
      },
      "options": [
        {
          "identifier": {
            "builderOptionCode": "string",
          },
        },
      ],
    }
  ],
}

If the top level optionSet property is provided, the top level options property will be ignored.
Both optionSets and options have a required item property action whose value can be one of "upsert" or "delete".

Setting Default/Base Options

We can set the default value for an option set in two different ways

{
  "options": [
    {
      "identifier": {
        "builderOptionCode": "string",
      },
      "setAsDefault": true
    }
  ],
}

{
  "optionSets": [
    {
      "identifier": {
        "docOptionSetId": "optionSet_HigharcOptionSetId",
      },
      "defaultValue": "option_HigharcOptionId"
    }
  ],
}

Targeting an Option Set via its Options

Many builders do not have an Option Set concept but still want to control Option Set properties via the API.

First we need to identify the Higharc Option Set ID for the option in question. One way can do this by using the Master Plan Options API.

Endpoint

GET /api/v1/builders/{builderId}/master-plans/{masterPlanId}/options

{
  "optionSets": [
    {
      "docOptionSetId": "string",
      "builderOptionSetCode": "string",
      "options": [
        {
          "builderOptionCode": "string",
        }
      ],
    }
  ],
}

Tip: Use this response to map builderOptionCode to docOptionSetId connecting Higharc’s data with your system.

We can then make requests in the format shown in the previous section.

Making an Option Operational

Operational options are hidden from home buyers, but still included in Home Plan Options exports. This is controlled by an option set property, salesCategory.

{
  "optionSets": [
    {
      "identifier": {
        "builderOptionSetCode": "string",
      },
      "salesCategory": "OPERATIONS"
    }
  ],
}

Clearing an Option Override

We can clear overrides in one of two ways. Either by removing all overrides at once for an option or option set, or removing the override on a single property.

{
  "options": [
    {
      "identifier": {
        "builderOptionCode": "string",
      },
      "action": "delete"
    }
  ],
}

{
  "options": [
    {
      "identifier": {
        "builderOptionCode": "string",
      },
      "price": null,
      // Other overridden properties can still remain
    }
  ],
}

Updating the Garage Handing on a Lot

If we wanted to set the garage handing for any home built on the lot, we can do so at the following endpoint.

Endpoint

PUT /api/v1/builders/{builderId}/lots/{lotId}

{
  "lot": {
    "garageHandingDirection": "left",
  },
}

If we need to be more targeted, we use the Lot Location Plan to mirror a home plan on a lot using the mirror option type.

Endpoint

PUT /api/v1/builders/{builderId}/option-templates/upsert

{
  "lotCommunityPlanId": "string",
  "optionSets": [
    {
      "identifier": {
        "docOptionSetId": "mirror",
      },
      "defaultValue": true
    }
  ],
}