Record gate attendance (limited pilot)

curl --request POST \
  --url https://api.buildpass.global/builders/{builderId}/projects/{projectId}/sign-on-events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-BuildPass-Api-Version: <x-buildpass-api-version>' \
  --data '
{
  "sourceEventId": "<string>",
  "workerId": "<string>",
  "type": "SIGN_ON",
  "occurredAt": "2023-11-07T05:31:56Z",
  "deviceId": "<string>"
}
'

import requests

url = "https://api.buildpass.global/builders/{builderId}/projects/{projectId}/sign-on-events"

payload = {
    "sourceEventId": "<string>",
    "workerId": "<string>",
    "type": "SIGN_ON",
    "occurredAt": "2023-11-07T05:31:56Z",
    "deviceId": "<string>"
}
headers = {
    "X-BuildPass-Api-Version": "<x-buildpass-api-version>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-BuildPass-Api-Version': '<x-buildpass-api-version>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    sourceEventId: '<string>',
    workerId: '<string>',
    type: 'SIGN_ON',
    occurredAt: '2023-11-07T05:31:56Z',
    deviceId: '<string>'
  })
};

fetch('https://api.buildpass.global/builders/{builderId}/projects/{projectId}/sign-on-events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.buildpass.global/builders/{builderId}/projects/{projectId}/sign-on-events",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'sourceEventId' => '<string>',
    'workerId' => '<string>',
    'type' => 'SIGN_ON',
    'occurredAt' => '2023-11-07T05:31:56Z',
    'deviceId' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "X-BuildPass-Api-Version: <x-buildpass-api-version>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.buildpass.global/builders/{builderId}/projects/{projectId}/sign-on-events"

	payload := strings.NewReader("{\n  \"sourceEventId\": \"<string>\",\n  \"workerId\": \"<string>\",\n  \"type\": \"SIGN_ON\",\n  \"occurredAt\": \"2023-11-07T05:31:56Z\",\n  \"deviceId\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-BuildPass-Api-Version", "<x-buildpass-api-version>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.buildpass.global/builders/{builderId}/projects/{projectId}/sign-on-events")
  .header("X-BuildPass-Api-Version", "<x-buildpass-api-version>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"sourceEventId\": \"<string>\",\n  \"workerId\": \"<string>\",\n  \"type\": \"SIGN_ON\",\n  \"occurredAt\": \"2023-11-07T05:31:56Z\",\n  \"deviceId\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.buildpass.global/builders/{builderId}/projects/{projectId}/sign-on-events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-BuildPass-Api-Version"] = '<x-buildpass-api-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"sourceEventId\": \"<string>\",\n  \"workerId\": \"<string>\",\n  \"type\": \"SIGN_ON\",\n  \"occurredAt\": \"2023-11-07T05:31:56Z\",\n  \"deviceId\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

POST

builders

{builderId}

projects

{projectId}

sign-on-events

Record gate attendance (limited pilot)

curl --request POST \
  --url https://api.buildpass.global/builders/{builderId}/projects/{projectId}/sign-on-events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-BuildPass-Api-Version: <x-buildpass-api-version>' \
  --data '
{
  "sourceEventId": "<string>",
  "workerId": "<string>",
  "type": "SIGN_ON",
  "occurredAt": "2023-11-07T05:31:56Z",
  "deviceId": "<string>"
}
'

import requests

url = "https://api.buildpass.global/builders/{builderId}/projects/{projectId}/sign-on-events"

payload = {
    "sourceEventId": "<string>",
    "workerId": "<string>",
    "type": "SIGN_ON",
    "occurredAt": "2023-11-07T05:31:56Z",
    "deviceId": "<string>"
}
headers = {
    "X-BuildPass-Api-Version": "<x-buildpass-api-version>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-BuildPass-Api-Version': '<x-buildpass-api-version>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    sourceEventId: '<string>',
    workerId: '<string>',
    type: 'SIGN_ON',
    occurredAt: '2023-11-07T05:31:56Z',
    deviceId: '<string>'
  })
};

fetch('https://api.buildpass.global/builders/{builderId}/projects/{projectId}/sign-on-events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.buildpass.global/builders/{builderId}/projects/{projectId}/sign-on-events",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'sourceEventId' => '<string>',
    'workerId' => '<string>',
    'type' => 'SIGN_ON',
    'occurredAt' => '2023-11-07T05:31:56Z',
    'deviceId' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "X-BuildPass-Api-Version: <x-buildpass-api-version>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.buildpass.global/builders/{builderId}/projects/{projectId}/sign-on-events"

	payload := strings.NewReader("{\n  \"sourceEventId\": \"<string>\",\n  \"workerId\": \"<string>\",\n  \"type\": \"SIGN_ON\",\n  \"occurredAt\": \"2023-11-07T05:31:56Z\",\n  \"deviceId\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-BuildPass-Api-Version", "<x-buildpass-api-version>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.buildpass.global/builders/{builderId}/projects/{projectId}/sign-on-events")
  .header("X-BuildPass-Api-Version", "<x-buildpass-api-version>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"sourceEventId\": \"<string>\",\n  \"workerId\": \"<string>\",\n  \"type\": \"SIGN_ON\",\n  \"occurredAt\": \"2023-11-07T05:31:56Z\",\n  \"deviceId\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.buildpass.global/builders/{builderId}/projects/{projectId}/sign-on-events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-BuildPass-Api-Version"] = '<x-buildpass-api-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"sourceEventId\": \"<string>\",\n  \"workerId\": \"<string>\",\n  \"type\": \"SIGN_ON\",\n  \"occurredAt\": \"2023-11-07T05:31:56Z\",\n  \"deviceId\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

Deployed for a limited, explicitly approved pilot. Existing integrations do not receive write:sign_on_events automatically. The pairing contract below requires agreement with the provider before rollout; deployment does not establish controller integration or general availability.

One physical event per request

Requires write:sign_on_events, a connected integrator and a worker-project site-access relationship. Reports observed attendance; it never grants or restores access. A revoked relationship still accepts historical attendance.

{
  "sourceEventId": "controller-event-100",
  "workerId": "wkr_clgbsb90b001qjy0f0eo1hspp",
  "type": "SIGN_ON",
  "occurredAt": "2026-09-15T01:00:00.000Z",
  "deviceId": "north-gate"
}

For sign-off, send a different stable event ID and explicitly reference the source sign-on ID for that visit:

{
  "sourceEventId": "controller-event-101",
  "sourceSignOnEventId": "controller-event-100",
  "workerId": "wkr_clgbsb90b001qjy0f0eo1hspp",
  "type": "SIGN_OFF",
  "occurredAt": "2026-09-15T03:00:00.000Z",
  "deviceId": "north-gate"
}

Times must be UTC with millisecond precision or less and cannot be in the future. Event/device IDs are at most 200 characters. Extra fields are rejected.

Retries, conflicts and late delivery

Event identity is scoped to integrator, builder and project, across credential rotation.
Replaying the same ID and payload returns 200 with duplicate: true.
Reusing an ID with different data returns 409 and changes nothing.
A new applied event returns 201. Sign-offs close only the explicitly referenced visit.
A sign-off received first returns 202, PENDING_SIGN_ON and a null attendance ID. It is stored durably and applied atomically when its sign-on arrives. Replay the sign-off to retrieve its current status.
A reference to another worker, a sign-off before sign-on, or a second distinct sign-off for the same visit returns 409.
An already manually closed or archived attendance record returns 409; provider retries do not overwrite administrator corrections.
Retry network errors or server failures with the original event ID and payload. Treat payload/pairing conflicts as reconciliation work, not a reason to generate a fresh ID.

{
  "data": {
    "id": "saevt_example",
    "sourceEventId": "controller-event-101",
    "status": "APPLIED",
    "signOnId": "signon_example",
    "duplicate": false
  }
}

Events are audited and projected into integration-generated BuildPass attendance records using the project’s timezone for day grouping. This does not run the interactive worker sign-on questionnaire, approve safety tasks, or establish controller authorization. Worker-app state, evacuation workflows, notifications and reporting acceptance must be verified before enabling a provider pilot. Rejected attempts and visitors are not supported by this endpoint.

Authorizations

Authorization

string

header

required

The access token received from the authorization server in the OAuth 2.0 flow.

Headers

X-BuildPass-Api-Version

enum<string>

default:v1

required

What API version to use.

Available options:

v1

Example:

"v1"

X-BuildPass-Region-Id

enum<string>

default:au1

Builder database region; defaults to au1.

Available options:

au1,

us1

Path Parameters

builderId

string

required

The ID of the builder

Example:

"buil_clgbsb90b001qjy0f0eo1hspp"

projectId

string

required

The ID of the project

Example:

"proj_clgbsb90b001qjy0f0eo1hspp"

Body

application/json

Option 1
Option 2

sourceEventId

string

required

Required string length: 1 - 200

workerId

string

required

Pattern: ^wkr_[a-zA-Z0-9]+$

type

enum<string>

required

Available options:

SIGN_ON

occurredAt

string<date-time>

required

UTC occurrence time, millisecond precision or less; cannot be in the future.

deviceId

string

Required string length: 1 - 200

Response

Identical event replay; current processing status returned.

Authentication

Builders

Projects

Site access (planned)

Meetings

Defects

Attachments

Photos

Subcontractors

Insurances

Prequalifications

SWMS

Inductions

Timesheets

Record gate attendance (limited pilot)

One physical event per request

Retries, conflicts and late delivery

Authorizations

Headers

Path Parameters

Body

Response

​One physical event per request

​Retries, conflicts and late delivery

Authorizations

Headers

Path Parameters

Body

Response

One physical event per request

Retries, conflicts and late delivery