Building an Integration with Konquest

Building an Integration with Konquest

Welcome to the Konquest integration guide. Before getting started, you'll need to authenticate with the API - see our Authentication Guide. The full API reference is also available in our API documentation.

 

---

1. Before You Start

Authentication

All API requests require a Bearer token in the Authorization header. See the Authentication Guide for details on obtaining a token using the Device Authorization Flow.

Understand the Account's Placement Configuration

Before processing placements, retrieve the account's placement settings. This tells you which placement rules are active and what modifier rulesets have been configured - information that is relevant when deciding which custom fields to include on your placements.

Note: Placement rules are configured by Konquest as part of account setup — you do not need to create or manage them. Retrieving them is useful for understanding which custom field values are expected. See Section 6 for more on custom fields.

---

2. Users (Beneficiaries)

Konquest users - referred to as beneficiaries in the context of placements - are the individuals who receive commission credit for placements. Before processing any placements, we recommend checking which users already exist in the account.

Recommended Workflow

1. Fetch all existing users from the Konquest account.
2. Match them against your own user records by ID or email address.
3. For any users who do not exist in Konquest, decide whether to create them via the API, skip them, or pass their details and allow the system to handle missing users gracefully (see below).
4. Complete all user synchronisation before processing placements.

Creating a User

The request body requires three fields: firstName, lastName, and email.

Handling Missing Users on Placements

When assigning beneficiaries to a placement, if you supply a user id that does not correspond to an existing Konquest user, the system will silently skip that beneficiary rather than returning an error. This means:

• If the user needs to receive commission credit: create them in Konquest before processing the placement.
• If you want to assign credit later: you can proceed without them — beneficiaries can be updated on a placement after creation.
• If you are not managing users via the API: you can omit beneficiary assignment entirely; users can be added manually within Konquest.

---

3. Creating Placements

Placements are the core data entity in Konquest. A placement represents a hire — either a permanent placement (known as a direct hire in the US) or a contract placement (known as a temp in the US). The placement type determines how revenue and commission are calculated and what additional data is required.

Core Placement Fields

Permanent Placements (Direct Hire)

A permanent placement (US: direct hire) represents a one-time placement fee for a candidate moving into full-time employment. Revenue is recognised from the fee provided at creation. After creating the placement, set or update the terms using the dedicated endpoint:

The permanent terms model accepts startDate (date-time) and fee, where fee is an object with currency (string) and value (number).

Contract Placements (Temp)

A contract placement (US: temp) represents an ongoing engagement billed periodically. Set fee to 0 at creation - all revenue is accumulated through timesheet entries (see Section 5). After creating the placement, set the contract terms:

The contract terms model currently accepts startDate (date-time). Charge and pay rates are carried at the timesheet level - include chargeAmount, chargeCurrency, payAmount, and payCurrency on each timesheet entry rather than on the contract terms.

Checking for Duplicate Placements

Before creating a placement, you may want to verify it does not already exist. Use the search query parameter on the list endpoint to look up by worker name or company. The response includes pagination fields (skipped, taken, totalPlacements) to support iterating over large result sets.

---

4. Updating Placements

Most placement fields can be updated individually after creation:

Important: PUT /api/placements/{id}/beneficiaries replaces all existing beneficiaries on the placement. Your request must include every beneficiary you want to retain, not just newly added ones.

Beneficiary Object

Each beneficiary in the array uses the following structure:

---

5. Attaching Timesheets

Timesheets are the mechanism through which contract/temp placements accumulate revenue over time. Each entry represents a billing period and carries the amount charged to the client and the amount paid to the worker.

Timesheet Fields

Note: If your source system provides only a single figure per period (e.g. a charge value only), pass it as chargeAmount and set payAmount to 0.

---

6. Custom Fields

Custom fields allow you to attach additional metadata to placements. They are not just labels — in Konquest they can act as drivers for accumulation rules, payment calculations, and burdens (employer costs such as payroll taxes, pension contributions, or National Insurance). Getting custom fields right is therefore important to ensure commission and billing calculations are correct.

Two Types of Custom Field

Custom Field Request Bodies

Placement custom field (SetCustomFieldModel): name (string) and value (string).

Value custom field (SetValueCustomFieldModel): name (string), value (string), and valueDate (date-time, must match the associated timesheet date).

Custom Fields as Rule Drivers

Placement rules in Konquest can evaluate custom field values to determine which commission rates, accumulation logic, or burden calculations apply to a placement. For example, a rule might apply a different commission percentage when a custom field called division equals Technology, or calculate an employer burden only when employment_type equals PAYE.

Incorrect, missing, or misspelled custom field values will result in the wrong rules being applied, which can mean incorrect commission calculations. Before going live, we recommend:

• Retrieving placement settings (GET /api/placements/settings) to understand active rules.
• Retrieving custom field names in use (GET /api/placements/custom-field-names) to ensure correct field names.
• Confirming expected values with the account owner, particularly for any fields that drive accumulation or burden rules.

---

7. Quick Reference: Endpoint Summary

---

8. Integration Review

Before going live, all third-party integrations must be submitted to Konquest for review and validation. To do this, send the following details to support@konquest.io:

• The endpoints your integration calls, and the purpose of each call
• The placement type(s) you are creating (permanent, contract, or both)
• Which custom fields you are setting
• Whether your integration creates users, or relies on users already existing in Konquest

This allows the Konquest team to verify that your integration is using the API correctly and that custom fields are aligned with the account's commission rules before any data is processed in a live environment.

---

9. Further Support

If you have questions not covered in this article, or if you believe your integration requires endpoints not listed above, please contact us before proceeding: support@konquest.io