{
  "openapi": "3.1.0",
  "info": {
    "title": "Blaaiz Platform API - Upload Customer Files",
    "version": "1.0.0",
    "description": "**Individual customers only.** Upload verification files for an individual customer using `file_id` values from the File API presigned upload. \n\n**Do not call this endpoint for `type=business` customers.** Business-type customers use a different flow: register beneficial owners, upload owner ID files via the dedicated owner-file endpoints, and register KYB documents via the document collection. See the [Business customer KYB guide](/guides/kyb/overview). Calling this endpoint for a business customer does nothing useful — the file is stored but the readiness check on `/submit` does not look at the legacy `id_file_path` for businesses, so verification will not start.\n\nNewly uploaded files override previous records. The `id_file` must be uploaded for the customer to be verified. The identity document must be a Driver's License, Passport, or Resident Permit for individual customers. ID cards (National Identity Cards) are not accepted. No other document types are accepted. All uploaded documents must be clear, legible, and authentic. Blurry, cropped, obscured, or unclear images will not be reviewed and will be rejected. Fraudulent or falsified documents will not be tolerated — repeated attempts will result in the customer being permanently blacklisted from the platform."
  },
  "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": {
      "UploadFilesRequest": {
        "type": "object",
        "properties": {
          "id_file": {
            "type": "string",
            "description": "file_id for the identity document (from File API presigned upload). The identity document must be a Driver's License, Passport, or Resident Permit for individual customers, or a Certificate of Incorporation for business customers. ID cards (National Identity Cards) are not accepted. The document image must be clear and legible — unclear or illegible images will be rejected. IMPORTANT: Including id_file in the request signals that document upload is complete and triggers the verification process. Other files (id_file_back, proof_of_address_file, liveness_check_file) can be uploaded before or alongside id_file, but verification will only begin once id_file is included in the request."
          },
          "id_file_back": {
            "type": "string",
            "description": "file_id for the back side of the identity document (from File API presigned upload). Use this when the identity document is two-sided (e.g. driver's license). Not required for single-sided documents (e.g. passport, certificate of incorporation)."
          },
          "proof_of_address_file": {
            "type": "string",
            "description": "file_id for proof of address."
          },
          "liveness_check_file": {
            "type": "string",
            "description": "file_id for liveness check."
          }
        }
      },
      "UploadFilesResponse": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          }
        },
        "required": [
          "message"
        ]
      },
      "Error": {
        "type": "object",
        "properties": {
          "status": {
            "type": "boolean"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "status",
          "message"
        ]
      }
    }
  },
  "paths": {
    "/api/external/customer/{id}/files": {
      "post": {
        "summary": "Upload files for a customer",
        "description": "**Individual customers only.** Upload verification files for an individual customer. Use `file_id` values from the File API presigned upload. Newly uploaded files override previous records. The `id_file` must be uploaded for verification.\n\n**Do not call this endpoint for `type=business` customers.** Business-type customers use the KYB flow — see [Business customer KYB](/guides/kyb/overview). The legacy `id_file_path` is not consulted by `/submit` for business customers, so calling this endpoint achieves nothing for them.\n\nThe identity document must be a Driver's License, Passport, or Resident Permit. ID cards (National Identity Cards) are not accepted. No other document types are 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.\n\nIMPORTANT: Verification is not instant. After documents are uploaded, they go through a review process. This typically takes a few minutes, but can take up to 2 hours if the documents require additional screening. Do not escalate before 2 hours — such enquiries will not be attended to. If verification has been pending for 5 hours or more, contact the operations team to expedite. Listen for the `customer.verified` or `customer.rejected` webhook to know when the review is complete.\n\nRequired 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/UploadFilesRequest"
              },
              "example": {
                "id_file": "file_123456",
                "id_file_back": "file_234567",
                "proof_of_address_file": "file_789012",
                "liveness_check_file": "file_345678"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Files uploaded successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UploadFilesResponse"
                },
                "example": {
                  "message": "Customer files uploaded successfully"
                }
              }
            }
          },
          "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"
                }
              }
            }
          }
        }
      }
    }
  }
}