List in-progress negotiations and check who needs to approve them

Please ensure that you have reviewed the prerequisites before following this guide.

We'll provide details on the following steps:

List the negotiations in a workspace that are still in progress

Narrow that list down to the negotiations that are waiting on an approval

For a single negotiation, see who the approvers are and which of them still need to decide

1. List in-progress negotiations

Request

Negotiations are assigned to workspaces (Sub-Accounts). You can list the in-progress negotiations for one of your workspaces using the endpoint:

GET https://sandbox-api.app.createiq.tech/api/v1/subAccounts/:subAccountId/negotiations?state=negotiating&pageIndex=0&pageSize=10&orderBy=lastAction&orderDirection=desc

We've used several parameters in this example, let's examine them:

state=negotiating: Negotiations that have been sent and are being negotiated by both parties, but haven't yet reached execution. This includes negotiations that are paused waiting for an approval.

pageIndex, pageSize: The page you would like, and how big the pages should be. pageSize must be between 5 and 100. You can vary these parameters to get other pages of results.

orderBy, orderDirection: How results should be sorted. In this case by the time of lastAction (last modified by anyone) and descending.

The state parameter can be repeated to include several states at once. For example, to also include negotiations you've drafted but not yet sent, and invitations that haven't been responded to yet:

GET https://sandbox-api.app.createiq.tech/api/v1/subAccounts/:subAccountId/negotiations?state=negotiating&state=draft&state=inviting&pageIndex=0&pageSize=10&orderBy=lastAction&orderDirection=desc

The state parameter accepts groups of states rather than the individual states shown in the Negotiation States article. The groups relevant to this guide are:

Group	Matches
`draft`	Created but not yet sent, including drafts waiting for approval before they can be sent
`inviting`	Sent to a counterparty and not yet responded to, including invitations the receiver has unlocked and is still drafting
`negotiating`	Being negotiated, confirmed by one side, or agreed by both sides and waiting for final document approval
`executing`	Agreed by all parties and waiting for signature pages
`executed`	Completed
`cancelled`	Cancelled
`approval`	Any negotiation that is currently waiting for an approval, whichever of the above groups it is in. We'll use this in step 2.
`electionLevelApprovals`, `finalDocumentApprovals`	The two halves of approval. See step 2.

Response

This endpoint returns:

Summary data for all the negotiations that appear on this page (under the key result). A standalone example of a single negotiation summary is in Appendix I of the List all completed negotiations guide.

Information about how many pages are available (under the key pagingMeta)

Lists of entities present in negotiations on this page for use in further filtering

Aggregate counts for all pages (under the key negotiationUIFilterCounts)

A read back of the parameters that were used to generate this response

💡 Pro tip

The aggregate counts include a states object that is keyed by the same group names as the state parameter above. If you want a quick dashboard of how many negotiations are waiting for approval without paging through the results, that's the place to look:


"negotiationUIFilterCounts": {
  "total": 42,
  "ourTurn": 17,
  "assignedToMe": 3,
  "states": {
    "draft": 4,
    "inviting": 6,
    "negotiating": 25,
    "approval": 5,
    "electionLevelApprovals": 3,
    "finalDocumentApprovals": 2,
    "executing": 2,
    "executed": 5
  },
  ...
}

2. Find the negotiations waiting for an approval

There are two kinds of approval in CreateiQ:

Election Level Approval: One or more individual elections (answers) have been moved away from an approved position and must be approved before the negotiation can be sent to the other party.

Final Document Approval: Both parties have confirmed their elections and the whole document must be approved before execution can begin.

Request

To list only the negotiations that are waiting on either kind of approval, use the approval state group:

GET https://sandbox-api.app.createiq.tech/api/v1/subAccounts/:subAccountId/negotiations?state=approval&pageIndex=0&pageSize=10&orderBy=lastAction&orderDirection=desc

To list only one kind, use state=electionLevelApprovals or state=finalDocumentApprovals instead.

Response

The same list response as step 1. Each negotiation summary in result carries a handful of fields that describe its approval position:

documentApprovalState: The state of Final Document Approval on your side of the negotiation. Pending means the document has been sent to your approvers and they haven't all decided yet.

electionApprovalState: The state of Election Level Approval on your side. Pending means at least one election is waiting for a decision.

externalDocumentApprovalState: The state of Final Document Approval on the other party's side, where that is visible to you.

approvers: The full names of the approvers who are being waited on. When Final Document Approval is pending these are the document approvers; otherwise, when Election Level Approval is pending, these are the election approvers. The key is omitted entirely when nothing is pending.

electionApprovalCounts: How many elections have been sent for approval (total), how many are still undecided (pending), and the same two numbers scoped to the user or API credential making the call (totalForMe and pendingForMe).

statusLabel: The human-readable status shown in the CreateiQ interface. This will read 'Election Approval required' or 'Document Approval required' when an approval is pending.

Each of the three approval state fields takes one of the values Pending, Approved, Rejected, ApprovalRequired or NoApprovalRequired, and is omitted when no approval rules have been set on that side.

Note that the state field of a negotiation summary does not change while an approval is pending: a negotiation waiting for Election Level Approval still reports a state of amending, and one waiting for Final Document Approval reports confirmed. Use the fields above, or the state=approval filter, to detect approvals rather than the state field.

Here are the relevant fields from a negotiation that has been sent for Final Document Approval:


{
  "id": "01806037-f5db-188b-6302-4b5d7c60b8fe",
  "state": "confirmed",
  "statusLabel": "Document Approval required",
  "documentApprovalState": "Pending",
  "electionApprovalState": "Approved",
  "electionApprovalCounts": {
    "total": 2,
    "pending": 0,
    "totalForMe": 0,
    "pendingForMe": 0
  },
  "approvers": [
    "Jane Doe",
    "Sam Patel"
  ],
  ...
}

We'll take the id of each negotiation forward into step 3.

💡 Pro tip

If you'd like the list of negotiations that a particular approver is being waited on for, for example to build a personal to-do list, add the approverUserId parameter:

GET https://sandbox-api.app.createiq.tech/api/v1/subAccounts/:subAccountId/negotiations?approverUserId=:userId&pageIndex=0&pageSize=10&orderBy=lastAction&orderDirection=desc

This returns only negotiations that have a pending approval against that user. It can be combined with approvalType=election or approvalType=general (Final Document Approval) to narrow it to one kind of approval. User IDs can be found by listing the users in your workspace:

GET https://sandbox-api.app.createiq.tech/api/v1/subaccount/:subAccountId/users

3. See who the approvers are and who has decided

The negotiation summary only gives you approver names. To see who the approvers are in detail, what the quorum is, and which approvers have already approved or rejected, fetch the full negotiation.

Request

GET https://sandbox-api.app.createiq.tech/api/v1/subAccounts/:subAccountId/negotiations/:negotiationId

Response

A full negotiation response (Appendix II of the List all completed negotiations guide). The approval detail lives under two keys:

documentApproval: The Final Document Approval for your side of the negotiation

electionApprovals: An object keyed by election ID, with one entry for each election that has approval rules set on it

Both use the same structure, shown in full in Appendix I below:

state: The same value as documentApprovalState or electionApprovalState in the summary.

approvalRules: The approvers currently configured for this document or election. This is who is entitled to approve. namedApprovers lists each approver with their userId, email, firstName, lastName and role; quorum is how many of them must approve; isBroken is true if one or more of them can no longer approve (for example because they've left the workspace), in which case that approver will carry a brokenBecause value.

approvalInProgress: The round of approval that is currently open, and the key you want for 'who still needs to approve'. It is only present while an approval is pending. Its namedApprovers list repeats each approver with two extra fields: decision, which is Pending, Approved or Rejected, and decisionReached, the time at which that decision was made. sentForApprovalOn is when the round started.

approval: The outcome of the most recent completed round, in the same shape as approvalInProgress. If there hasn't been a round yet this simply mirrors approvalRules.

So, for a negotiation waiting on Final Document Approval, the approvers who still need to act are the entries in documentApproval.approvalInProgress.namedApprovers whose decision is Pending. The round completes once the number of Approved entries reaches the quorum, or once any approver rejects.

For Election Level Approval, do the same for each entry in electionApprovals. The list electionsToApprove gives you the IDs of the elections that the calling user or API credential is being waited on for.

Approvers for the other party, under externalDocumentApproval, are returned with their decisions but without names or contact details, and carry a type of AnonymousApproverDto rather than NamedApproverDto.

💡 Pro tip

Once an approval round has completed it moves out of approvalInProgress. If you'd like the full history of every round a negotiation has been through, including any comments the approvers left with their decisions, use the endpoint:

GET https://sandbox-api.app.createiq.tech/api/v1/subAccounts/:subAccountId/negotiations/:negotiationId/approvals/history

🚀 Congratulations! You can now list the negotiations in progress in a workspace, spot the ones that are stuck waiting for an approval, and find out exactly who needs to act on them.

Appendix I: The documentApproval key from a single Negotiation

This example shows a Final Document Approval that has been sent to two approvers with a quorum of two. One has approved and one is still pending.


"documentApproval": {
  "state": "Pending",
  "approvalRules": {
    "namedApprovers": [
      {
        "userId": "0176707c-4754-4738-b85a-2f11ca211e68",
        "email": "jane@global-investment-bank.invalid",
        "firstName": "Jane",
        "lastName": "Doe",
        "role": "approver",
        "isAdvisor": false,
        "profileColour": "#6750A4"
      },
      {
        "userId": "0176707c-4754-4738-b85a-2f11ca211e69",
        "email": "sam@global-investment-bank.invalid",
        "firstName": "Sam",
        "lastName": "Patel",
        "role": "manager",
        "isAdvisor": false,
        "profileColour": "#008569"
      }
    ],
    "guestApprovalRequests": [],
    "quorum": 2,
    "isBroken": false
  },
  "approval": {
    "namedApprovers": [
      {
        "type": "NamedApproverDto",
        "userId": "0176707c-4754-4738-b85a-2f11ca211e68",
        "email": "jane@global-investment-bank.invalid",
        "firstName": "Jane",
        "lastName": "Doe",
        "role": "approver",
        "isAdvisor": false,
        "profileColour": "#6750A4"
      },
      {
        "type": "NamedApproverDto",
        "userId": "0176707c-4754-4738-b85a-2f11ca211e69",
        "email": "sam@global-investment-bank.invalid",
        "firstName": "Sam",
        "lastName": "Patel",
        "role": "manager",
        "isAdvisor": false,
        "profileColour": "#008569"
      }
    ],
    "sentForApprovalOn": "2025-05-10T10:15:21.818992Z",
    "quorum": 2
  },
  "approvalInProgress": {
    "namedApprovers": [
      {
        "type": "NamedApproverDto",
        "userId": "0176707c-4754-4738-b85a-2f11ca211e68",
        "email": "jane@global-investment-bank.invalid",
        "firstName": "Jane",
        "lastName": "Doe",
        "role": "approver",
        "isAdvisor": false,
        "decisionReached": "2025-05-10T10:22:08.985271Z",
        "decision": "Approved",
        "profileColour": "#6750A4"
      },
      {
        "type": "NamedApproverDto",
        "userId": "0176707c-4754-4738-b85a-2f11ca211e69",
        "email": "sam@global-investment-bank.invalid",
        "firstName": "Sam",
        "lastName": "Patel",
        "role": "manager",
        "isAdvisor": false,
        "decision": "Pending",
        "profileColour": "#008569"
      }
    ],
    "sentForApprovalOn": "2025-05-10T10:15:21.818992Z",
    "quorum": 2
  }
}