PATCH

Push Booking Result

/fmi/data/vLatest/databases/{db}/layouts/QC_Booking/records/{recordId}

Called by CLIV to push a QC booking result back into BasicPSF after a booking request has been processed. The result is matched to the original request using the internalOrderReference field and can be either Booked (confirmed, with inspection date and inspector) or Unavailable (rejected).

🧪

UAT Environment

Use this environment for integration testing. Test record references will be provided by the PPS integration team.

Property	Value
Base URL	`https://pps.basicpsf.com`
Database	`BasicPSF_Test`
Full endpoint	`https://pps.basicpsf.com/fmi/data/vLatest/databases/BasicPSF_Test/layouts/QC_Booking/records/{recordId}`

⚠️

Production Environment

Do not use for testing. All writes affect live PPS operational data. Separate production credentials are required.

Property	Value
Base URL	`https://pps.basicpsf.com`
Database	`BasicPSF_PPS`
Full endpoint	`https://pps.basicpsf.com/fmi/data/vLatest/databases/BasicPSF_PPS/layouts/QC_Booking/records/{recordId}`

Overview

This endpoint is part of the CLIV inbound integration for BasicPSF. It is called by CLIV after a QC booking request (submitted by PPS) has been either confirmed or rejected on the CLIV platform.

Because the BasicPSF API does not support a single-step find-and-update operation, CLIV must complete a two-step process: first find the target record by internalOrderReference, then PATCH that record with the result data.

Authentication

The BasicPSF API uses session-based authentication. This is separate to the OAuth 2.0 client credentials flow used by CLIV's own API.

💡

Recommended approach

Obtain a fresh session token immediately before each booking result push. Do not cache tokens across separate push operations. Token inactivity timeout is 15 minutes.

Property	Value
Method	Session token (Bearer)
Token lifetime	15 minutes inactivity
Credentials	Provided by BasicData via secure channel
Header format	`Authorization: Bearer {session_token}`

Request Flow

Each booking result push requires four sequential API calls.

Authenticate — obtain a session token

POST to the sessions endpoint with your Base64-encoded credentials. Extract the token from the response.

HTTP

POST /fmi/data/vLatest/databases/{db}/sessions

Content-Type: application/json
Authorization: Basic <base64(username:password)>

// Body must be an empty JSON object
{}

Response

{
  "response": {
    "token": "d6b85d1d8bea5f31a92b09b7..."
  },
  "messages": [{ "code": "0", "message": "OK" }]
}

ℹ️

Base64 encoding

The Authorization header value is Basic followed by the Base64 encoding of username:password. Most HTTP client libraries handle this automatically when you provide credentials.

Find the record by internalOrderReference

POST to the _find endpoint to locate the QC_Booking record. Extract the recordId from the response — this is required for step 3.

HTTP

POST /fmi/data/vLatest/databases/{db}/layouts/QC_Booking/_find

Content-Type: application/json
Authorization: Bearer {session_token}

{
  "query": [
    { "internalOrderReference": "==ORD-2025-00123" }
  ]
}

Response

{
  "response": {
    "data": [
      {
        "recordId": "42",
        "fieldData": {
          "internalOrderReference": "ORD-2025-00123",
          ...
        }
      }
    ]
  }
}

⚠️

Use exact match operator

Always prefix the search value with == to prevent partial matches. If the find returns zero records, do not proceed — log the error and notify the PPS integration team.

PATCH the record with the booking result

Use the recordId from step 2 to update the record. Send all four fields in the request body regardless of the booking result.

HTTP

PATCH /fmi/data/vLatest/databases/{db}/layouts/QC_Booking/records/{recordId}

Content-Type: application/json
Authorization: Bearer {session_token}

{
  "fieldData": {
    "CLIV_Booking_Result": "Booked",
    "bookingDate":         "04/28/2025",
    "InspectorName":       "Zhang Wei"
  }
}

Close the session

DELETE the session token to cleanly invalidate it after the push is complete.

HTTP

DELETE /fmi/data/vLatest/databases/{db}/sessions/{session_token}

Authorization: Bearer {session_token}

⚠️

Always close the session

The FM session is not closed automatically after the PATCH. Always send the DELETE immediately after receiving the PATCH response. Failing to do this leaves idle sessions open on FM Server until the 15-minute inactivity timeout.

Payload Reference

The following fields must be included in the PATCH body. The internalOrderReference field is used in step 2 to locate the record and is not included in the PATCH body.

Field	Type	Required	Description
`CLIV_Booking_Result`	String	Required	Must be exactly `"Booked"` or `"Unavailable"`. Case sensitive.
`bookingDate`	Date	Conditional	Required when `CLIV_Booking_Result` is `"Booked"`. Send as empty string `""` when Unavailable. Format: `MM/DD/YYYY`
`InspectorName`	String	Conditional	Required when `CLIV_Booking_Result` is `"Booked"`. Full name of the assigned inspector. Send as empty string `""` when Unavailable.

Match field (find step only)

Field	Type	Description
`internalOrderReference`	String	The PPS internal order reference sent to CLIV in the original booking request. Used to locate the record. Not written to the record.

Date format

Field	Format	Example
`bookingDate`	`MM/DD/YYYY`	`04/28/2025`

💡

CLIV_Booking_Confirmed_At is auto-stamped by BasicPSF

Do not include CLIV_Booking_Confirmed_At in the PATCH body. BasicPSF automatically sets this field to the server timestamp when the record is committed.

ℹ️

Empty strings not null

When a booking is Unavailable, send bookingDate and InspectorName as empty strings ("") rather than null or omitting the fields. BasicPSF handles empty strings correctly for date and text fields.

Response Codes

200

Record updated successfully. Response code will be "0".

401

Unauthorized

Session token is invalid or has expired. Re-authenticate and retry with a new token.

404 (FM 401)

Record not found

The find step returned no results for the given internalOrderReference. Do not proceed with the PATCH. Log the error and notify the PPS integration team.

404 (FM 105)

Layout not found

The layout name in the URL is incorrect. Verify the endpoint URL matches exactly: QC_Booking.

400 (FM 500)

Bad request

Malformed JSON or an unrecognised field name in the request body. Check field names match exactly as documented.

500

Server error

Retry the request. If the issue persists, contact BasicData via the PPS integration team.

Full Examples

Successful booking (Booked)

PATCH body

{
  "fieldData": {
    "CLIV_Booking_Result": "Booked",
    "bookingDate":         "04/28/2025",
    "InspectorName":       "Zhang Wei"
  }
}

Unavailable booking

PATCH body

{
  "fieldData": {
    "CLIV_Booking_Result":       "Unavailable",
    "bookingDate": "",
    "InspectorName":  ""
  }
}

Successful response

Response · 200 OK

{
  "response": {},
  "messages": [
    { "code": "0", "message": "OK" }
  ]
}