{
  "openapi": "3.1.0",
  "info": {
    "title": "Blaaiz Platform API - Add Customer KYC",
    "version": "1.0.0",
    "description": "Add KYC / KYB profile details for a customer. Applies to both individual and business-type customers; for businesses you can additionally pass operating-address fields (`operating_street`, `operating_city`, `operating_state`, `operating_zip_code`, `operating_country`). Verification does not start from this endpoint — the customer stays `PENDING` until you complete the type-specific upload + submit flow. See [Business customer KYB](/guides/kyb/overview) for businesses or [Creating your first payout](/guides/creating-first-payout) for individuals.\n\n**Type-specific fields.** Only fields that match the customer's `type` are accepted. The `operating_*` address fields are business-only; sending them on an `individual` customer fails the entire request. Send only what applies to the customer you're updating.\n\n**Postal-code validation per address.** `zip_code` is validated against the customer's persisted `country`. `operating_zip_code` is validated against `operating_country` — sent in this request, or, if absent, the persisted value. Each address is self-describing.\n\n**`operating_country` is required when any other `operating_*` field is sent** at create time (`POST /customer`); on this endpoint, sending an `operating_*` field without `operating_country` is allowed only if `operating_country` is already persisted on the KYC data row.\n\nThe customer's `country` itself is not edited here — it lives on the customer (top-level), not on KYC data. Use `PUT /customer/{id}` to change `country` or `incorporation_country`."
  },
  "tags": [
    {
      "name": "Customer"
    }
  ],
  "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": {
              "customer:write": "Create and update customers and KYC data."
            }
          }
        }
      }
    },
    "schemas": {
      "AddKycRequest": {
        "type": "object",
        "properties": {
          "dob": {
            "type": "string",
            "format": "date",
            "description": "Date of birth (YYYY-MM-DD)."
          },
          "street": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "zip_code": {
            "type": "string"
          },
          "id_expiry_date": {
            "type": "string",
            "format": "date"
          },
          "id_issue_date": {
            "type": "string",
            "format": "date"
          },
          "state": {
            "type": "string"
          },
          "operating_street": {
            "type": "string",
            "description": "Business-only. Operating address street, when different from the registered address."
          },
          "operating_city": {
            "type": "string",
            "description": "Business-only. Operating address city."
          },
          "operating_state": {
            "type": "string",
            "description": "Business-only. Operating address state."
          },
          "operating_zip_code": {
            "type": "string",
            "description": "Business-only. Operating address postcode. Validated against `operating_country` (request value or persisted)."
          },
          "operating_country": {
            "type": "string",
            "description": "Business-only. Operating address country, ISO alpha-2. Anchors postal-code validation for `operating_zip_code`."
          }
        }
      },
      "Customer": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "business_id": {
            "type": "string"
          },
          "first_name": {
            "type": "string",
            "nullable": true
          },
          "last_name": {
            "type": "string",
            "nullable": true
          },
          "business_name": {
            "type": "string",
            "nullable": true
          },
          "type": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "country": {
            "type": "string"
          },
          "id_type": {
            "type": "string",
            "nullable": true,
            "description": "Set for individual customers. May be null on business customers (which identify via `registration_number` + `incorporation_country` instead)."
          },
          "id_number": {
            "type": "string",
            "nullable": true,
            "description": "Set for individual customers. May be null on business customers."
          },
          "verification_status": {
            "type": "string"
          },
          "kyc_data": {
            "type": "object"
          }
        },
        "required": [
          "id",
          "business_id",
          "type",
          "email",
          "country",
          "verification_status"
        ]
      },
      "AddKycResponse": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          },
          "data": {
            "$ref": "#/components/schemas/Customer"
          }
        },
        "required": [
          "message",
          "data"
        ]
      },
      "Error": {
        "type": "object",
        "properties": {
          "status": {
            "type": "boolean"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "status",
          "message"
        ]
      }
    }
  },
  "paths": {
    "/api/external/customer/{id}/kyc-data": {
      "post": {
        "summary": "Add KYC details",
        "description": "Add KYC details for a customer. Verification stays PENDING until documents are uploaded and reviewed. The customer's country must match the country on the identity document submitted for KYC. Accepted identity documents: Driver's License, Passport, or Resident Permit for individual customers, Certificate of Incorporation for business customers. ID cards (National Identity Cards) are not accepted. All uploaded documents must be clear, legible, and authentic — unclear images will be rejected. Fraudulent or falsified documents will result in the customer being permanently blacklisted from the platform. Required scope: `customer:write`.",
        "tags": [
          "Customer"
        ],
        "security": [
          {
            "oauth2ClientCredentials": [
              "customer:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Customer ID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AddKycRequest"
              },
              "example": {
                "dob": "1990-01-01",
                "street": "123 Main St",
                "city": "Lagos",
                "zip_code": "100001",
                "id_expiry_date": "2030-12-31"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "KYC data updated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AddKycResponse"
                },
                "example": {
                  "message": "Business customer KYC data updated successfully.",
                  "data": {
                    "id": "9d4c4ec5-59ea-4130-bf8a-6a5edec401ee",
                    "business_id": "9d4c4ec5-572d-49de-a362-f01ed09f2b1b",
                    "first_name": "John",
                    "last_name": "Doe",
                    "business_name": null,
                    "type": "individual",
                    "email": "john.doe@company.com",
                    "country": "NG",
                    "id_type": "passport",
                    "id_number": "6733823632872",
                    "verification_status": "PENDING",
                    "kyc_data": {}
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "status": false,
                  "message": "Invalid request parameters"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "status": false,
                  "message": "Invalid or missing access token"
                }
              }
            }
          }
        }
      }
    }
  }
}