Working with Employees through the API

API Access and Security

All requests to the Employees 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.

• Required API Key Scope: employees.read is required for both retrieving a single employee and listing employees.

API Base URL

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

Retrieving a Single Employee Record

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

Requirements

• HTTP Method: GET

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

Important Note

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

Example API Call

Request

GET https://<builder-prime-subdomain>.builderprime.com/api/employees/v1/1000356

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

Successful Response (Excerpt)

{
  "success": true,
  "data": {
    "id": 1000356,
    "firstName": "Bob",
    "lastName": "Damob",
    "email": "bob@example.com",
    "isProjectManager": false,
    "isCurrentEmployee": true,
    "timezone": "America/New York"
    // ... more employee properties
  }
}

Listing Multiple Employee Records

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

Requirements

• HTTP Method: GET

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

Available Query Parameters

Example API Call (Pagination)

This example requests up to 100 employee records, starting with page 0.

Request

GET https://<builder-prime-subdomain>.builderprime.com/api/employees/v1?limit=100&page=0

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

Successful Response (Excerpt)

{
  "success": true,
  "data": [
    {
      "id": 1000356,
      "firstName": "Bob",
      "lastName": "Damob",
      "isSalesPerson": false
      // ... more employee properties
    }
  ]
}