# `Weavr.Corporates`
[🔗](https://github.com/iamkanishka/weavr/blob/main/lib/weavr/resources/corporates.ex#L1)

Corporate identities — companies onboarded to the Weavr platform.

All paths, request fields, response fields, and enums in this module
are verified against `api.weavr.io/products/multi/openapi/corporates/`.

## Key concepts

A Corporate identity represents a company. Before it can create instruments
or perform transactions, it must complete KYB (Know Your Business) due
diligence. The root user must be a director or legal representative of the
company, and must verify their email and mobile as part of the process.

Once a Corporate has completed KYB, the following fields are **locked and
cannot be updated via the API** (contact Weavr support to change them):
root user name/surname/email/mobile, business address, date of birth.

## Company types

`"SOLE_TRADER"`, `"LLC"`, `"PUBLIC_LIMITED_COMPANY"`,
`"LIMITED_LIABILITY_PARTNERSHIP"`, `"NON_PROFIT_ORGANISATION"`

## Root user company positions

`"DIRECTOR"`, `"AUTHORISED_REPRESENTATIVE"`

# `charge_fee`

```elixir
@spec charge_fee(Weavr.Config.t(), String.t(), map()) ::
  {:ok, map()} | {:error, Weavr.Error.t()}
```

Charges a pre-defined custom fee to the corporate.

`POST /corporates/fees/charge` — fees are collected into your Revenue Account.
Custom fees are configured in the Multi Portal.

# `create`

```elixir
@spec create(Weavr.Config.t(), map(), keyword()) ::
  {:ok, map()} | {:error, Weavr.Error.t()}
```

Creates a new Corporate identity.

`POST /corporates` — no `auth_token` needed (uses `api-key` only).

## Required fields in `attrs`

  * `"profileId"` — from Multi Portal > API Credentials
  * `"rootUser"` — object with `name`, `surname`, `email`, `mobile`,
    `companyPosition` (`"DIRECTOR"` or `"AUTHORISED_REPRESENTATIVE"`)
  * `"company"` — object with `name`, `type`, `registrationCountry`,
    `businessAddress`
  * `"ipAddress"` — the end-user's IP address
  * `"baseCurrency"` — ISO 4217 code (e.g. `"GBP"`, `"EUR"`)

## Notable optional fields

  * `"tag"` — custom searchable field
  * `"industry"` — see module doc for enum values
  * `"sourceOfFunds"` — enum, see module doc
  * `"feeGroup"` — for programmes with differentiated fee tiers
  * `"acceptedTerms"` — must be `true` to confirm T&C acceptance

# `get`

```elixir
@spec get(Weavr.Config.t(), String.t()) :: {:ok, map()} | {:error, Weavr.Error.t()}
```

Retrieves the details of the logged-in corporate.

`GET /corporates` — uses `auth_token` of the corporate's root/authorised user.

# `get_kyb`

```elixir
@spec get_kyb(Weavr.Config.t(), String.t()) ::
  {:ok, map()} | {:error, Weavr.Error.t()}
```

Returns the KYB status for the logged-in corporate.

`GET /corporates/kyb`

# `send_email_verification`

```elixir
@spec send_email_verification(Weavr.Config.t(), String.t()) ::
  {:ok, map()} | {:error, Weavr.Error.t()}
```

Sends an email verification code to the corporate root user.

`POST /corporates/verification/email/send` — step 1 of email verification,
required before KYB can be started. On Sandbox the code is always `"123456"`.

# `start_kyb`

```elixir
@spec start_kyb(Weavr.Config.t(), String.t()) ::
  {:ok, map()} | {:error, Weavr.Error.t()}
```

Initiates the KYB due diligence process for the logged-in corporate.

`POST /corporates/kyb` — returns a `reference` to initialise the KYB UI
Component that must be embedded in your application.

# `update`

```elixir
@spec update(Weavr.Config.t(), String.t(), map()) ::
  {:ok, map()} | {:error, Weavr.Error.t()}
```

Updates the logged-in corporate's details.

`PATCH /corporates` — KYB-locked fields (name, email, address, DOB) are
ignored once KYB is complete. See module doc.

# `verify_email`

```elixir
@spec verify_email(Weavr.Config.t(), String.t(), String.t()) ::
  :ok | {:error, Weavr.Error.t()}
```

Verifies the corporate root user's email using the code from
`send_email_verification/2`.

`POST /corporates/verification/email/verify` — step 2. On Sandbox the code
is always `"123456"`. Returns 204 No Content on success.

---

*Consult [api-reference.md](api-reference.md) for complete listing*