How can I connect List of Contracts with List of People

Q&A
1

Let me describe the situation. I import employees (List of People endpoint), and then I want to import a list of contracts (List of Contracts). However, the list of people and the list of contracts do not match by the fields people.ID = contract.worker.id, or rather, they match very little. For example, some records do not contain a worker at all, some contracts have workers who are not in the list of people, and so on.
And please clarify for me dependencies between Organization/Team → Employee → Contract → Invoices, with endpoints and Connective fields. Thanks!

2

Hi @IronRat,

Apologies for the delay, and thanks for your patience! We’ve thoroughly investigated the issue you raised, but after multiple checks, we couldn’t find any inconsistencies in the data returned by the People and Contracts APIs.

One possible reason for the mismatch you’re seeing is pagination—both APIs paginate results, meaning they don’t return the entire dataset at once. If your implementation isn’t handling pagination properly, some employees or contracts might be missing from your view.

Regarding Contracts with worker.id = null

These are contracts that have been created and sent as invitations, but the worker hasn’t yet created an account. Until they sign up, their status remains “waiting for sign”, and their worker.id stays empty.

Additionally, we are currently experiencing a temporary issue with some types of contracts, where the worker.id is missing even though the worker exists. As a workaround, you can retrieve the worker’s information by making a request to:

GET /contracts/{contract_id} → This will return the full contract details, including the correct worker information.

Our team is currently doing it’s best to get this fixed as soon as possible.

Data Relationships & Connectivity Fields

Here’s a breakdown of how the data flows between different APIs:

:one: Organization / Teams → People

:pushpin: Endpoints:

  • GET /teams → Returns all teams in an organization.
    • Field: data[].id (Team ID)
  • GET /people → Lists all employees.
    • Field: data[].employments[].team.id (Team ID of the employee)

:link: Connectivity:
people.employments.team.id = teams.id

:two: People → Contracts

:pushpin: Endpoints:

  • GET /people → Lists employees, including their IDs.
    • Field: data[].id (Employee ID)
  • GET /contracts → Lists contracts, where each contract is linked to a worker.
    • Field: data[].worker.id (Worker ID from people.id)

:link: Connectivity:
contracts.worker.id = people.id

:warning: Possible Issue: If worker.id is missing, it means the worker hasn’t created an account yet.

:three: Contracts → Invoices

:pushpin: Endpoints:

  • GET /invoices → Returns all invoices.
    • Field: data[].contract_id (References contracts.id)

:link: Connectivity:
invoices.contract_id = contracts.id

:warning: Exception: If it’s a service invoice, it won’t be linked to a contract and won’t have a contract_id.

Next Steps

  1. Check if your API calls are handling pagination correctly to ensure all people and contracts are fetched.
  2. For contracts with missing worker.id, verify whether those workers have activated their accounts.
  3. Cross-check your data using the connectivity fields above to ensure proper mapping.

Let me know if you need any further clarification! :blush:

Best,
Ashot