{
  "openapi": "3.1.0",
  "info": {
    "title": "Blaaiz Platform API - Get Identification Type",
    "version": "1.0.0",
    "description": "Every country has its own national or tax identification system — SSN in the US, BVN in Nigeria, NINO in the UK, and so on. When creating a customer for a Virtual Bank Account (especially USD), you need to collect a `tin` value. This endpoint tells you what that identification is called for a given country and customer type, so you can label the field correctly in your UI and collect the right value from your customer. The returned `label` is the display name (e.g. \"Social Security Number\") and the value your customer provides should be saved as the `tin` field on the customer."
  },
  "tags": [
    {
      "name": "Virtual Bank Accounts"
    }
  ],
  "servers": [
    {
      "url": "https://api-prod.blaaiz.com"
    },
    {
      "url": "https://api-dev.blaaiz.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "oauth2ClientCredentials": {
        "type": "oauth2",
        "description": "Use your OAuth client credentials to obtain a short-lived Bearer token from POST /oauth/token.",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "/oauth/token",
            "scopes": {
              "virtual-account:read": "Read virtual accounts."
            }
          }
        }
      }
    },
    "schemas": {
      "IdentificationType": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "description": "Human-readable label to display in your UI (e.g. \"Bank Verification Number\" for Nigeria, \"Social Security Number\" for US). Use this as the field label when collecting the value from your customer."
          },
          "country": {
            "type": "string",
            "description": "The resolved country code used for the lookup."
          },
          "customer_type": {
            "type": "string",
            "description": "The customer type used for the lookup (individual or business). Different types may return different identification requirements for the same country."
          }
        },
        "required": [
          "label",
          "country",
          "customer_type"
        ]
      },
      "IdentificationTypeResponse": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          },
          "data": {
            "$ref": "#/components/schemas/IdentificationType"
          }
        },
        "required": [
          "message",
          "data"
        ]
      },
      "Error": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          }
        },
        "required": [
          "message"
        ]
      }
    }
  },
  "paths": {
    "/api/external/virtual-bank-account/identification-type": {
      "get": {
        "summary": "Get identification type",
        "description": "Look up the country-specific identification type that a customer must provide as their `tin` value. Each country uses a different identification system (e.g. SSN in the US, BVN in Nigeria, NINO in the UK), and individual vs business customers within the same country may require different types. Call this endpoint before creating or updating a customer to know what field label to show in your UI and what value to collect. Save the collected value as the customer's `tin` field. Required scope: `virtual-account:read`.",
        "tags": [
          "Virtual Bank Accounts"
        ],
        "security": [
          {
            "oauth2ClientCredentials": [
              "virtual-account:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "customer_id",
            "in": "query",
            "required": false,
            "description": "Unique identifier of the customer. If provided, country and type are not required.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "country",
            "in": "query",
            "required": false,
            "description": "Two-letter country code (e.g., NG). Required if customer_id is not provided.",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 2
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "Customer type. Required if customer_id is not provided. Possible values: business, individual.",
            "schema": {
              "type": "string",
              "enum": [
                "business",
                "individual"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Identification type retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IdentificationTypeResponse"
                },
                "examples": {
                  "nigeria_individual": {
                    "summary": "Nigeria — Individual",
                    "value": {
                      "message": "Identification type retrieved successfully.",
                      "data": {
                        "label": "Bank Verification Number",
                        "country": "NG",
                        "customer_type": "individual"
                      }
                    }
                  },
                  "us_individual": {
                    "summary": "United States — Individual",
                    "value": {
                      "message": "Identification type retrieved successfully.",
                      "data": {
                        "label": "Social Security Number",
                        "country": "US",
                        "customer_type": "individual"
                      }
                    }
                  },
                  "us_business": {
                    "summary": "United States — Business",
                    "value": {
                      "message": "Identification type retrieved successfully.",
                      "data": {
                        "label": "Employer Identification Number",
                        "country": "USA",
                        "customer_type": "business"
                      }
                    }
                  },
                  "uk_individual": {
                    "summary": "United Kingdom — Individual",
                    "value": {
                      "message": "Identification type retrieved successfully.",
                      "data": {
                        "label": "National Insurance Number",
                        "country": "GB",
                        "customer_type": "individual"
                      }
                    }
                  },
                  "canada_individual": {
                    "summary": "Canada — Individual",
                    "value": {
                      "message": "Identification type retrieved successfully.",
                      "data": {
                        "label": "Social Insurance Number",
                        "country": "CA",
                        "customer_type": "individual"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "status": false,
                  "message": "Invalid or missing access token"
                }
              }
            }
          }
        }
      }
    }
  }
}