Create Business Customer

Onboard a business customer with full KYC information.

Endpoint

POST /partner/v1/customers/business

Request

Headers

Name	Type	Required	Description
X-API-Key	string	Yes	Your partner API key
Content-Type	string	Yes	application/json

Body

{
  "cnpj": "12345678000199",
  "legal_name": "Empresa LTDA",
  "trade_name": "Nome Fantasia",
  "email": "[e-mail]",
  "phone": "[phone]",
  "address": {
    "street": "Rua Example",
    "number": "123",
    "complement": "Sala 1",
    "neighborhood": "Centro",
    "city": "São Paulo",
    "state": "SP",
    "postal_code": "01234567"
  },
  "owners": [
    {
      "owner_type": "partner",
      "name": "João Silva",
      "social_name": "João",
      "document": "12345678900",
      "email": "[e-mail]",
      "phone": "[phone]",
      "birth_date": "1990-01-15",
      "nationality_country_code": "BR",
      "tax_residence_country_code": "BR",
      "address": {
        "street": "Rua Residencial",
        "number": "456",
        "complement": "Apto 101",
        "neighborhood": "Jardins",
        "city": "São Paulo",
        "state": "SP",
        "postal_code": "04567890"
      },
      "ownership": {
        "ownership_type": "direct",
        "ownership_bps": 5000
      }
    }
  ],
  "metadata": {
    "external_id": "your_internal_id"
  },
  "config": {
    "auto_send_owner_sms": true,
    "auto_send_owner_email": true
  }
}

Business fields

Field	Type	Required	Description
cnpj	string	Yes	Business CNPJ (14 digits)
legal_name	string	Yes	Legal company name
trade_name	string	No	Trade/brand name
email	string	Yes	Company email
phone	string	Yes	Company phone (E.164 format)
address	object	Yes	Company address
owners	array	Yes	List of business owners
metadata	object	No	Custom metadata (JSON)
config	object	No	Configuration options

Address fields

Field	Type	Required	Description
street	string	Yes	Street name
number	string	Yes	Street number
complement	string	No	Address complement
neighborhood	string	Yes	Neighborhood
city	string	Yes	City
state	string	Yes	State (2-letter code)
postal_code	string	Yes	Postal code (CEP)

Owner fields

Field	Type	Required	Description
owner_type	string	Yes	partner, representative, or other_partner
name	string	Yes	Full legal name
social_name	string	No	Social/preferred name
document	string	Yes	CPF (11 digits)
email	string	Yes	Email address
phone	string	Yes	Phone (E.164 format)
birth_date	string	Yes	Birth date (YYYY-MM-DD)
nationality_country_code	string	Yes	Nationality (ISO 3166-1 alpha-2)
tax_residence_country_code	string	Yes	Tax residence country
address	object	Yes	Owner’s address
ownership	object	Yes	Ownership details

Ownership fields

Field	Type	Required	Description
ownership_type	string	Yes	direct or indirect
ownership_bps	integer	Yes	Ownership percentage in basis points (5000 = 50%)

Response

Success (201 Created)

{
  "id": "cus_abc123xyz"
}

Validation errors (400 Bad Request)

{
  "error": "invalid_cnpj",
  "message": "The provided CNPJ is invalid"
}

{
  "error": "invalid_phone",
  "message": "The provided phone number is invalid"
}

{
  "error": "invalid_owner",
  "message": "Invalid CPF for owner"
}

Example

curl -X POST https://api.bipa.tech/partner/v1/customers/business \
  -H "X-API-Key: your_partner_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "cnpj": "12345678000199",
    "legal_name": "Empresa LTDA",
    "email": "[e-mail]",
    "phone": "[phone]",
    "address": {
      "street": "Rua Example",
      "number": "123",
      "neighborhood": "Centro",
      "city": "São Paulo",
      "state": "SP",
      "postal_code": "01234567"
    },
    "owners": [
      {
        "owner_type": "partner",
        "name": "João Silva",
        "document": "12345678900",
        "email": "[e-mail]",
        "phone": "[phone]",
        "birth_date": "1990-01-15",
        "nationality_country_code": "BR",
        "tax_residence_country_code": "BR",
        "address": {
          "street": "Rua Residencial",
          "number": "456",
          "neighborhood": "Jardins",
          "city": "São Paulo",
          "state": "SP",
          "postal_code": "04567890"
        },
        "ownership": {
          "ownership_type": "direct",
          "ownership_bps": 10000
        }
      }
    ]
  }'