Working with Projects through the API

API Access and Security

All requests to the Projects API require a secret key, which must be created in your Builder Prime app with the appropriate scope for the action you want to perform.

• Security Header: The secret key must be included in the request headers with the key x-api-key. The required scope for this key depends on the operation:

• projects.read: For retrieving a single project or listing projects.

• projects.create: For creating a new project.

• projects.edit: For modifying an existing project

   

API Base URL

The base URL for the Projects endpoint depends on the action you're performing, but always starts with your specific subdomain.

• For all the following examples you must replace <builder-prime-subdomain> with the specific subdomain specified by your customer. 

1. Retrieving a Single Project Record

To get the details of a specific project, you need to use the project's internal ID in the request path.

Requirements

• HTTP Method: GET

• URL: Must include the internal projectId in the path.

• API Key Scope: projects.read 

Important Note

If you do not specify the projectId in the path, the API will attempt to retrieve a list of projects instead.

Example API Call

Request

GET https://<builder-prime-subdomain>.builderprime.com/api/projects/v1/<projectId>

Header: x-api-key: [Your Secret Key]

Successful Response (Example)

{
  "success": true,
  "data": {
    "id": 111,
    "projectName": "Replace windows for customer",
    "estimatedValue": 15000.00,
    "clientFirstName": "John",
    "projectStatusDescription": "In Progress"
    // ... more project properties
  }
}

2. Listing Multiple Project Records

To retrieve a list of projects, use a GET request to the base projects URL. You can optionally add parameters to filter the results.

Requirements

• HTTP Method: GET 

• URL: https://<builder-prime-subdomain>.builderprime.com/api/projects/v1 

• API Key Scope: projects.read 

Available Query Parameters

You can add the following parameters to the URL to filter and manage the results:

Example API Call (Filtering and Pagination)

Request

GET https://<builder-prime-subdomain>.builderprime.com/api/projects/v1?limit=10&page=0&project-status=In%20Progress&last-modified-since=1700000000000

Header: x-api-key: [Your Secret Read Key]

Successful Response (Example)

{
  "success": true,
  "data": [
    {
      "id": 111,
      "projectName": "Replace windows for customer",
      "projectStatusDescription": "In Progress"
      // ... more projects
    }
  ]
}

3. Creating a New Project Record

To create a new project, you must send a POST request with a JSON body containing the new project's data.

Requirements

• HTTP Method: POST 

• URL: https://<builder-prime-subdomain>.builderprime.com/api/projects/v1 

• Content Type: The request must include the header Content-Type: application/json.

• API Key Scope: projects.create 

Required Fields

The following fields are mandatory for creating a new project:

• clientOpportunityId

• projectStatus

Important Notes on Formatting

• If a field is not applicable, you should omit it from the request.

• When specifying personnel (Project Manager, Foreman, Sales Person), you can use their internal id, emailAddress, or their firstName and lastName.

Example API Call (Create Project)

Request

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

Header: Content-Type: application/json

Header: x-api-key: [Your Secret Create Key]

{
  "clientOpportunityId": 1234,
  "projectStatus": "Estimate Request",
  "projectName": "New Window Install",
  "projectManager": {
    "emailAddress": "projectmgr@company.com"
  },
  "workSiteAddressLinel": "123 Main Street",
  "estimatedValue": 15000,
  "customFields": [
    {
      "customFieldName": "Budget",
      "customFieldValue": "5000"
    }
  ]
}

Successful Response (Excerpt)

{
  "success": true,
  "data": {
    "id": 123456789
    // ... other properties of newly created project
  }
}

4. Modifying an Existing Project Record

To update an existing project, you must send a POST request to the specific project's ID with a JSON body containing the changes.

Requirements

• HTTP Method: POST

• URL: Must include the internal projectId in the path

• Content Type: The request must include the header Content-Type: application/json.

• API Key Scope: projects.edit 

Important Notes on Formatting

• If you do not specify the projectId in the path, the API will attempt to create a new project instead. 

• Omit any properties that you do not want to modify.

• Providing a null or blank value for a property in the request will remove any data currently stored for that property.

• Values for fields that are selected from drop-down lists in Builder Prime (like projectStatus or projectType) must match exactly to one of those values for the update to be accepted.

Example API Call (Modify Project Status and Value)

This example updates the project status and estimated value for project ID 111.

Request

POST https://<builder-prime-subdomain>.builderprime.com/api/projects/v1/111

Header: Content-Type: application/json

Header: x-api-key: [Your Secret Edit Key]

{
  "projectStatus": "In Progress",
  "estimatedValue": 16000,
  "salesPerson": { 
    "firstName": "Abby",
    "lastName": "Dabby"
  }
}

Successful Response (Excerpt)

{
  "success": true,
  "data": {
    "id": 123456789
    // ... other properties of updated project
  }
}