Counterparty Assurance

This guide provides a comprehensive walkthrough of creating and managing a Request for Information (RFI) using the API, focusing on a counterparty assurance scenario. Counterparty assurance is the process of verifying the identity, compliance status, and credibility of a business partner before engaging in financial transactions.

By following this guide, you will learn how to:

Select an appropriate scenario for counterparty assurance.
Create an RFI directly (or optionally, start with a draft).
Respond to the RFI with necessary information.
Review and complete the RFI process.

Prerequisites

API Credentials: You must have your client_id and client_secret provided by BNDRY.
Teams Setup: Ensure that the necessary teams (creator, broker, assignee) are created and you have their IDs.
Scenario Availability: The counterparty assurance scenario must be available in your environment.

Authentication

Before making any API calls, authenticate with the API using OAuth 2.0 Client Credentials flow to obtain an access token.

Generate an Access Token

Request

POST /v1alpha/tokens:generate
Host: api.{customer}.app.identitii.com
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "{your_client_id}",
  "client_secret": "{your_client_secret}"
}

Replace {customer} with your assigned customer identifier.
Replace {your_client_id} and {your_client_secret} with your actual credentials.

Response

{
  "access_token": "{access_token}",
  "token_type": "Bearer",
  "expires_in": 3600
}

Usage

Include the access_token in the Authorization header for all subsequent API calls:

Authorization: Bearer {access_token}

Step 1: Select the Counterparty Assurance Scenario

Identify and select the scenario suitable for counterparty assurance.

List Available Scenarios

Request

GET /request/v1alpha/scenarios
Host: api.{customer}.app.identitii.com
Authorization: Bearer {access_token}

Response

{
  "scenarios": [
    {
      "name": "scenarios/counterparty-assurance",
      "display_name": "Counterparty Assurance",
      "rfi_input_json_schema": { /* Schema details */ },
      /* Other scenario details */
    },
    /* Other scenarios */
  ]
}

Action

Locate the scenario with "display_name": "Counterparty Assurance".
Note the name field (e.g., scenarios/counterparty-assurance) for use in the next steps.

Step 2: Create an RFI

You can create an RFI directly without creating a draft. This step streamlines the process by initiating the RFI in a single operation.

Request

POST /request/v1alpha/scenarios/counterparty-assurance/rfis
Host: api.{customer}.app.identitii.com
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "input": {
    "counterpartyName": "ABC Corp",
    "country": "US",
    "registrationNumber": "123456789"
  },
  "creator_team": "teams/creator-team-id",
  "broker_team": "teams/broker-team-id",
  "assignee_team": "teams/assignee-team-id"
}

Replace teams/creator-team-id, teams/broker-team-id, and teams/assignee-team-id with your actual team IDs.

Response

{
  "name": "scenarios/counterparty-assurance/rfis/rfi456",
  "uid": "unique-rfi-uid",
  "state": "OPEN",
  "input": {
    "counterpartyName": "ABC Corp",
    "country": "US",
    "registrationNumber": "123456789"
  },
  "creator_team": "teams/creator-team-id",
  "broker_team": "teams/broker-team-id",
  "current_assignee_team": "teams/assignee-team-id",
  "initial_assignee_team": "teams/assignee-team-id",
  "create_time": "2023-10-01T12:35:00Z",
  /* Other RFI details */
}

Action

Note the name of the RFI (e.g., scenarios/counterparty-assurance/rfis/rfi456) for subsequent steps.

Optional Step: Create a Draft RFI

If you prefer to compose and refine your RFI before making it active, you can create a draft and publish it later. This step is optional.

Create a Draft

Request

POST /request/v1alpha/scenarios/counterparty-assurance/drafts
Host: api.{customer}.app.identitii.com
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "input": {
    "counterpartyName": "ABC Corp",
    "country": "US",
    "registrationNumber": "123456789"
  },
  "creator_team": "teams/creator-team-id",
  "broker_team": "teams/broker-team-id",
  "assignee_team": "teams/assignee-team-id"
}

Response

{
  "name": "scenarios/counterparty-assurance/drafts/draft123",
  "uid": "unique-draft-uid",
  /* Draft details */
}

Publish the Draft to Create an RFI

Request

POST /request/v1alpha/scenarios/counterparty-assurance/drafts/draft123:publish
Host: api.{customer}.app.identitii.com
Authorization: Bearer {access_token}
Content-Type: application/json

{}

Response

{
  "rfi": {
    "name": "scenarios/counterparty-assurance/rfis/rfi456",
    "uid": "unique-rfi-uid",
    "state": "OPEN",
    /* RFI details */
  }
}

Note: After publishing the draft, proceed with the steps for managing the RFI as described below.

Step 3: Respond to the RFI

The assignee team provides answers to the RFI's questions.

Request

POST /request/v1alpha/scenarios/counterparty-assurance/rfis/rfi456:respond
Host: api.{customer}.app.identitii.com
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "answers": {
    "companyRegistrationDetails": {
      "text": "Registration verified. Number matches official records."
    },
    "adverseMediaCheck": {
      "text": "No adverse media found for ABC Corp as of the latest check."
    },
    "complianceStatus": {
      "text": "ABC Corp complies with all relevant industry regulations."
    }
  }
}

The keys in the answers object correspond to question IDs defined in the scenario.

Response

{
  "name": "scenarios/counterparty-assurance/rfis/rfi456",
  "state": "IN_PROGRESS",
  "current_assignee_team": "teams/assignee-team-id",
  /* Updated RFI details */
}

Action

The RFI state transitions from OPEN to IN_PROGRESS.
Ensure all required questions are answered.

Step 4: Submit the RFI for Review

The assignee team submits the RFI responses for the broker team's review.

Request

POST /request/v1alpha/scenarios/counterparty-assurance/rfis/rfi456:submit
Host: api.{customer}.app.identitii.com
Authorization: Bearer {access_token}
Content-Type: application/json

{}

Response

{
  "name": "scenarios/counterparty-assurance/rfis/rfi456",
  "state": "IN_REVIEW",
  "current_assignee_team": "teams/broker-team-id",
  /* Updated RFI details */
}

Action

The RFI state transitions to IN_REVIEW.
The current_assignee_team changes to the broker team.

Step 5: Review the RFI Responses

The broker team reviews the answers and approves or rejects them.

Approve All Responses

Request

POST /request/v1alpha/scenarios/counterparty-assurance/rfis/rfi456:review
Host: api.{customer}.app.identitii.com
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "reviews": {
    "companyRegistrationDetails": "APPROVED",
    "adverseMediaCheck": "APPROVED",
    "complianceStatus": "APPROVED"
  }
}

Response

{
  "name": "scenarios/counterparty-assurance/rfis/rfi456",
  "state": "COMPLETE",
  "current_assignee_team": "teams/creator-team-id",
  /* Updated RFI details */
}

Action

The RFI state transitions to COMPLETE.
The current_assignee_team reverts to the creator team.

If Any Response is Rejected

If any answer requires further action, reject it to send the RFI back to the assignee team.

Request

POST /request/v1alpha/scenarios/counterparty-assurance/rfis/rfi456:review
Host: api.{customer}.app.identitii.com
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "reviews": {
    "companyRegistrationDetails": "APPROVED",
    "adverseMediaCheck": "REJECTED",
    "complianceStatus": "APPROVED"
  }
}

Response

{
  "name": "scenarios/counterparty-assurance/rfis/rfi456",
  "state": "IN_PROGRESS",
  "current_assignee_team": "teams/assignee-team-id",
  /* Updated RFI details */
}

Action

The RFI state reverts to IN_PROGRESS.
The assignee team must provide additional information for the rejected answers.

Step 6: Complete the RFI

Once all answers are approved, the RFI process is complete.

Confirm Completion

Verify that the RFI is marked as COMPLETE.

Request

GET /request/v1alpha/scenarios/counterparty-assurance/rfis/rfi456
Host: api.{customer}.app.identitii.com
Authorization: Bearer {access_token}

Response

{
  "name": "scenarios/counterparty-assurance/rfis/rfi456",
  "state": "COMPLETE",
  /* RFI details */
}

Additional Considerations

Error Handling

Check for Errors: Always inspect API responses for errors and handle them gracefully.
Status Codes: Refer to the Error Handling section in the main documentation for details.

ETags for Concurrency Control

Optimistic Locking: Use the etag field when updating or deleting resources to prevent conflicts.
Include ETag: Provide the etag in the If-Match header or request body as required.

State Diagram

Understanding the RFI state transitions helps in managing the workflow effectively.

OPEN ➔ IN_PROGRESS: When the assignee starts responding.
IN_PROGRESS ➔ IN_REVIEW: When the assignee submits for review.
IN_REVIEW ➔ COMPLETE: When the broker approves all responses.
IN_REVIEW ➔ IN_PROGRESS: When the broker rejects any response.

Conclusion

You have successfully navigated an end-to-end flow of creating and managing an RFI for counterparty assurance using the API. This process ensures that sensitive information is securely exchanged and verified, maintaining compliance with industry regulations.

By integrating this workflow into your systems, you can automate counterparty assurance processes, reduce manual efforts, and enhance operational efficiency.

Next Steps

Implement Error Handling: Ensure your application can handle API errors gracefully.
Automate Workflows: Consider automating this flow within your systems for efficiency.
Explore Further: Review other scenarios and API capabilities to expand your integration.

Note: Replace placeholders like {customer}, {access_token}, {your_client_id}, {your_client_secret}, and resource IDs with your actual values when making API calls.

Counterparty Assurance

Prerequisites

Authentication

Generate an Access Token

Step 1: Select the Counterparty Assurance Scenario

List Available Scenarios

Step 2: Create an RFI

Request

Optional Step: Create a Draft RFI

Create a Draft

Publish the Draft to Create an RFI

Step 3: Respond to the RFI

Request

Step 4: Submit the RFI for Review

Request

Step 5: Review the RFI Responses

Approve All Responses

Request

If Any Response is Rejected

Request

Step 6: Complete the RFI

Confirm Completion

Additional Considerations

Error Handling

ETags for Concurrency Control

State Diagram

Conclusion

Next Steps

Was this helpful?