Use Cases
/
Customer Onboarding
Last updated

Customer Onboarding

This guide provides a comprehensive walkthrough of creating and managing a Request for Information (RFI) using the Identitii API, focusing on a customer onboarding scenario. Customer onboarding involves collecting and verifying information from new clients to comply with KYC (Know Your Customer) and AML (Anti-Money Laundering) regulations.

By following this guide, you will learn how to:

  • Select an appropriate scenario for customer onboarding.
  • Create an RFI directly (or optionally, start with a draft).
  • Respond to the RFI with necessary customer 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 customer onboarding 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 Customer Onboarding Scenario

Identify and select the scenario suitable for customer onboarding.

List Available Scenarios

Request

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

Response

{
  "scenarios": [
    {
      "name": "scenarios/customer-onboarding",
      "display_name": "Customer Onboarding",
      "rfi_input_json_schema": { /* Schema details */ },
      /* Other scenario details */
    },
    /* Other scenarios */
  ]
}

Action

  • Locate the scenario with "display_name": "Customer Onboarding".
  • Note the name field (e.g., scenarios/customer-onboarding) 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/customer-onboarding/rfis
Host: api.{customer}.app.identitii.com
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "input": {
    "customerName": "Jane Smith",
    "address": "456 Elm Street, Suite 300, Metropolis, USA",
    "identificationDocument": {
      "type": "Passport",
      "number": "A12345678",
      "expiryDate": "2030-12-31"
    }
  },
  "creator_team": "teams/onboarding-team-id",
  "broker_team": "teams/compliance-team-id",
  "assignee_team": "teams/customer-service-team-id"
}
  • Replace teams/onboarding-team-id, teams/compliance-team-id, and teams/customer-service-team-id with your actual team IDs.

Response

{
  "name": "scenarios/customer-onboarding/rfis/rfi789",
  "uid": "unique-rfi-uid",
  "state": "OPEN",
  "input": {
    "customerName": "Jane Smith",
    "address": "456 Elm Street, Suite 300, Metropolis, USA",
    "identificationDocument": {
      "type": "Passport",
      "number": "A12345678",
      "expiryDate": "2030-12-31"
    }
  },
  "creator_team": "teams/onboarding-team-id",
  "broker_team": "teams/compliance-team-id",
  "current_assignee_team": "teams/customer-service-team-id",
  "initial_assignee_team": "teams/customer-service-team-id",
  "create_time": "2023-10-01T12:35:00Z",
  /* Other RFI details */
}

Action

  • Note the name of the RFI (e.g., scenarios/customer-onboarding/rfis/rfi789) 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/customer-onboarding/drafts
Host: api.{customer}.app.identitii.com
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "input": {
    "customerName": "Jane Smith",
    "address": "456 Elm Street, Suite 300, Metropolis, USA",
    "identificationDocument": {
      "type": "Passport",
      "number": "A12345678",
      "expiryDate": "2030-12-31"
    }
  },
  "creator_team": "teams/onboarding-team-id",
  "broker_team": "teams/compliance-team-id",
  "assignee_team": "teams/customer-service-team-id"
}

Response

{
  "name": "scenarios/customer-onboarding/drafts/draft456",
  "uid": "unique-draft-uid",
  /* Draft details */
}

Publish the Draft to Create an RFI

Request

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

{}

Response

{
  "rfi": {
    "name": "scenarios/customer-onboarding/rfis/rfi789",
    "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 (e.g., customer service team) provides answers to the RFI's questions.

Request

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

{
  "answers": {
    "personalInformation": {
      "text": "Name: Jane Smith, DOB: 1990-05-15"
    },
    "addressVerification": {
      "text": "Address confirmed via utility bill."
    },
    "idDocumentVerification": {
      "text": "Passport number A12345678 verified. Expiry date 2030-12-31."
    },
    "pepCheck": {
      "text": "No PEP (Politically Exposed Person) status detected."
    },
    "sanctionsCheck": {
      "text": "No matches found in sanctions lists."
    }
  }
}
  • The keys in the answers object correspond to question IDs defined in the scenario.

Response

{
  "name": "scenarios/customer-onboarding/rfis/rfi789",
  "state": "IN_PROGRESS",
  "current_assignee_team": "teams/customer-service-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 (e.g., compliance team) review.

Request

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

{}

Response

{
  "name": "scenarios/customer-onboarding/rfis/rfi789",
  "state": "IN_REVIEW",
  "current_assignee_team": "teams/compliance-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/customer-onboarding/rfis/rfi789:review
Host: api.{customer}.app.identitii.com
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "reviews": {
    "personalInformation": "APPROVED",
    "addressVerification": "APPROVED",
    "idDocumentVerification": "APPROVED",
    "pepCheck": "APPROVED",
    "sanctionsCheck": "APPROVED"
  }
}

Response

{
  "name": "scenarios/customer-onboarding/rfis/rfi789",
  "state": "COMPLETE",
  "current_assignee_team": "teams/onboarding-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/customer-onboarding/rfis/rfi789:review
Host: api.{customer}.app.identitii.com
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "reviews": {
    "personalInformation": "APPROVED",
    "addressVerification": "REJECTED",
    "idDocumentVerification": "APPROVED",
    "pepCheck": "APPROVED",
    "sanctionsCheck": "APPROVED"
  }
}

Response

{
  "name": "scenarios/customer-onboarding/rfis/rfi789",
  "state": "IN_PROGRESS",
  "current_assignee_team": "teams/customer-service-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/customer-onboarding/rfis/rfi789
Host: api.{customer}.app.identitii.com
Authorization: Bearer {access_token}

Response

{
  "name": "scenarios/customer-onboarding/rfis/rfi789",
  "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 customer onboarding using the API. This process ensures that customer information is securely collected, verified, and complies with regulatory requirements.

By integrating this workflow into your systems, you can automate customer onboarding 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.

Previous page
Next page