Working with meetings through the API

API Access and Security

All requests to the Meetings API require a secret key. This key 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.

• Content Type: For POST requests (Create and Modify), the header Content-Type: application/json is required.

API Base URL

The base URL for the Meetings endpoint depends on the action you're performing, and you must replace <builder-prime-subdomain> with your specific customer subdomain.

Retrieving a Single Meeting Record

To get the details of a specific meeting, you must include the meeting's internal ID in the request path.

Requirements

• HTTP Method: GET

• URL: Must include the internal <meetingId> in the path.

Important Note

If the <meetingId> is not specified in the path, the API will attempt to retrieve a list of meetings instead.

Example API Call:

Request

GET https://<builder-prime-subdomain>.builderprime.com/api/meetings/v1/<meetingId>

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

Successful Response (Excerpt)

{
  "success": true,
  "data": {
    "id": 2176,
    "title": "Estimate for Johnny Cash",
    "location": "200 Caudill Dr, Hendersonville, TN 37075",
    "startDateTime": 1740875400000,
    "employeeFirstName": "Hermoine",
    "meetingTypeName": "Sales Meeting"
    // ... more meeting properties
  }
}

Listing Multiple Meeting Records

To retrieve a list of meetings, use a GET request to the base meetings URL. You must use date parameters to define the time range.

Requirements

• HTTP Method: GET

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

• Required Query Parameters: start-date-from and start-date-to.

Available Query Parameters

Example API Call (Filtering and Pagination):

This example requests up to 10 meetings, starting from page 0, that begin between two specific epoch times.

Request

GET https://<builder-prime-subdomain>.builderprime.com/api/meetings/v1?start-date-from=1740000000000&start-date-to=1742000000000&limit=10&page=0

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

Successful Response (Excerpt)

{
  "success": true,
  "data": [
    {
      "id": 2176,
      "title": "Estimate for Johnny Cash",
      "startDateTime": 1740875400000
      // ... more meetings
    }
  ]
}

Creating a New Meeting Record

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

Requirements

• HTTP Method: POST

• Content Type: Content-Type: application/json

Important Notes on Formatting

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

• When specifying the employee, you can use their internal id, email address, or their firstName and lastName.

Example API Call (Create Meeting)

Request

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

Header: Content-Type: application/json

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

{
  "clientOpportunityId": 102988,
  "title": "Created from API 1",
  "location": "5 Spooner St, Providence, RI 02907",
  "startDateTime": 1742403600000,
  "endDateTime": 1742410800000,
  "employee": {
    "id": 50,
    "firstName": "Betty",
    "lastName": "Brown"
  },
  "meetingTypeId": 1011,
  "reminders": [
    {
      "unitsBefore": 30,
      "unitType": "MINUTES"
    }
  ]
}

Successful Response (Excerpt)

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

Modifying an Existing Meeting Record

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

Requirements

• HTTP Method: POST

• URL: Must include the internal <meetingId> in the path.

• Content Type: Content-Type: application/json.

Important Notes on Formatting

• If you do not specify the <meetingId> in the path, the API will attempt to create a new meeting 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 selected from drop-down lists in Builder Prime must match exactly for the update to be accepted.

Example API Call (Modify Location and Employee)

This example updates the location and employee for meeting ID 123456789.

Request

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

Header: Content-Type: application/json

Header: x-api-key: [Your_Secret_Key]

{
  "location": "100 New Street, Providence, RI",
  "employee": {
    "email": "newemployee@example.com"
  }
}

Successful Response (Excerpt)

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

Deleting a Single Meeting Record

To permanently remove a meeting record, you must submit a DELETE request with the internal meeting ID in the URL path.

Requirements

• HTTP Method: DELETE

• URL: Must include the internal <meetingId> in the path.

• API Key Scope: meetings.delete

Example API Call (Delete Meeting)

Request

DELETE https://<builder-prime-subdomain>.builderprime.com/api/meetings/v1/123456789

Header: x-api-key: [Your_Secret_Key]

Successful Response

{
  "success": true
}

Meeting Reference Data Queries

The following sections detail how to retrieve read-only data for Meeting Types and Meeting Results, which are necessary for creating or modifying meeting records.

Meeting Types Endpoint

This endpoint is used to retrieve configured meeting types (e.g., "Sales Meeting").

API Base URL

Requirements

• API Key Scope: meetingtypes.read  

Retrieving a Single Meeting Type

To retrieve one meeting type, include its internal ID in the path. If the ID is omitted, the API will attempt to retrieve a list of meeting types instead.

Example API Call (Get Single Meeting Type)

Request

GET https://<builder-prime-subdomain>.builderprime.com/api/meeting-types/v1/1011

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

Successful Response (Excerpt) 

{
  "success": true,
  "data": {
    "id": 1011,
    "name": "Sales Meeting",
    "isDefaultMeetingType": true,
    "isSalesMeeting": true
  }
}

Listing Meeting Types

You can list all meeting types, with optional parameters for pagination.

Available Query Parameters

Example API Call (List Meeting Types)

Request

GET https://<builder-prime-subdomain>.builderprime.com/api/meeting-types/v1?limit=100

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

Successful Response (Excerpt) 

{
  "success": true,
  "data": [
    {
      "id": 1011,
      "name": "Sales Meeting",
      "isDefaultMeetingType": true,
      "isSalesMeeting": true
    }
  ]
}

Meeting Results Endpoint

This endpoint is used to retrieve configured meeting results (e.g., "Sale").

API Base URL

Requirements

• API Key Scope: meetingresults.read 

Retrieving a Single Meeting Result

To retrieve one meeting result, include its internal ID in the path. If the ID is omitted, the API will attempt to retrieve a list of meeting results instead.

Request

GET https://<builder-prime-subdomain>.builderprime.com/api/meeting-results/v1/1001

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

Successful Response (Excerpt) 

{
  "success": true,
  "data": {
    "id": 1001,
    "name": "Sale",
    "isSalesMeeting": true
  }
}

Listing Meeting Results

You can list all meeting results, with optional parameters for pagination.

Available Query Parameters

Example API Call (List Meeting Results)

Request

GET https://<builder-prime-subdomain>.builderprime.com/api/meeting-results/v1?limit=100

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

Successful Response (Excerpt) 

{
  "success": true,
  "data": [
    {
      "id": 1001,
      "name": "Sale",
      "isSalesMeeting": true
    }
  ]
}

Best Practices

• Test your requests using a tool like Postman before deploying.

• Double-check spelling of all list values like firstName as they must exactly match the options in Builder Prime.

• Keep your secret key private. Do not share it or expose it in frontend code.

Need Help?

If you run into issues or need clarification, contact your Builder Prime support rep via email at support@builderprime.com.