Working with Clients through the API

Authentication

All API requests must be authenticated using a secret key, which you'll receive from your Builder Prime account. This key should be included in every request:

• Security Header: The secret key must be included in the request headers with the key x-api-key.
• Content Type: For POST requests (Create and Modify), the header Content-Type: application/json is required.

Base URL/endpoint

All requests begin with this format:

Replace <builder-prime-subdomain> with the unique subdomain for your Builder Prime account (provided by your administrator).

For example, for the account customhomes.builderprime.com, the API endpoint would be in the format https://customhomes.builderprime.com/api/clients

Creating a New Client (Lead/Opportunity)

Endpoint:
POST https://<builder-prime-subdomain>.builderprime.com/api/clients/v1

Content-Type: application/json

Example JSON Body:

{
  "firstName": "John",
  "lastName": "Smith",
  "email": "johnsmith3@gmail.com",
  "mobilePhone": "+18005554444",
  "addressLine1": "123 Main Street",
  "city": "Los Angeles",
  "state": "CA",
  "zip": "12345",
  "companyName": "Widgets Galore",
  "leadStatusName": "Lead Received",
  "leadSourceName": "Facebook",
  "salesPersonFirstName": "Alice",
  "salesPersonLastName": "Thompson",
  "secretKey": "YOUR_SECRET_KEY",
  "customFields": [
    {
      "customFieldName": "Budget",
      "customFieldValue": "5000"
    },
    {
      "customFieldName": "Referred By",
      "customFieldValue": "Axl Rose"
    }
  ]
}

Tips:

• Phone numbers should be in E.164 format: start with + followed by the country code.

• Omit fields that aren't needed. Do not send empty strings—those will be ignored.

• leadStatusName, leadSourceName, className, and similar fields must match exactly with Builder Prime’s configured values.

Modifying an Existing Client

Endpoint:

POST https://<builder-prime-subdomain>.builderprime.com/api/clients/v1/<opportunityId>

Replace <opportunityId> with the internal ID of the lead/opportunity you want to update (which you can find using the GET request explained below).

Content-Type: application/json

Example JSON Body: