@spec add_authorized_person(String.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, Solaris.Error.t()}

Adds an authorized person to a person's account. Triggers a change request if the person account already has an authorized person.

@spec authorize_mobile_number(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, Solaris.Error.t()}

Initiates an OTP SMS challenge to verify the mobile number. Rate-limited to 60 SMS/hour.

@spec confirm_mobile_number(String.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, Solaris.Error.t()}

Confirms the OTP sent to the mobile number.

Returns {:error, %Error{code: :forbidden}} if OTP is expired or invalid.

Examples

{:ok, result} = Solaris.Onboarding.Persons.confirm_mobile_number("cper_123", "123456")

@spec create(
  map(),
  keyword()
) :: {:ok, map()} | {:error, Solaris.Error.t()}

Creates a new person.

Required fields (vary by country/product — see Solaris docs)

• :first_name
• :last_name
• :email
• :birth_date — ISO 8601 date string or Date struct
• :nationality — ISO 3166-1 alpha-2 country code

Optional fields

• :salutation — "MR" | "MS" | "DIVERSE" | "UNKNOWN"

• :address — %{line_1, postal_code, city, country}
• :mobile_number — E.164 format
• :fatca_relevant — boolean
• :expected_monthly_revenue_cents
• :business_purpose
• :industry

Examples

{:ok, person} = Solaris.Onboarding.Persons.create(%{
  first_name: "Jane",
  last_name: "Doe",
  email: "jane@example.com",
  birth_date: "1990-01-15",
  nationality: "DE"
})

@spec create_mobile_number(String.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, Solaris.Error.t()}

Registers a mobile number for a person.

Only one mobile number per person. The number must be verified via OTP before it's usable for 2FA. API automatically normalizes formatting.

Examples

{:ok, mobile} = Solaris.Onboarding.Persons.create_mobile_number("cper_123", "+491701234567")

@spec create_tax_identification(String.t(), map(), keyword()) ::
  {:ok, map()} | {:error, Solaris.Error.t()}

Creates a tax identification record for a person.

• First submission must be primary: true
• Adding a new primary automatically demotes the old primary
• One tax ID per country per person

Examples

{:ok, tax_id} = Solaris.Onboarding.Persons.create_tax_identification("cper_123", %{
  country: "DE",
  number: "12345678901",
  primary: true,
  reason_no_number: nil
})

@spec delete_document(String.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, Solaris.Error.t()}

Deletes a document.

@spec delete_mobile_number(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, Solaris.Error.t()}

Deletes the registered mobile number. Triggers a change request if the number was already confirmed.

@spec download_document(String.t(), String.t(), keyword()) ::
  {:ok, binary()} | {:error, Solaris.Error.t()}

Downloads a document's raw binary content.

@spec get(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, Solaris.Error.t()}

Retrieves a specific person by ID.

Examples

{:ok, person} = Solaris.Onboarding.Persons.get("cper_123")

@spec get_document(String.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, Solaris.Error.t()}

Retrieves document metadata.

@spec get_language(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, Solaris.Error.t()}

Retrieves the person's language settings.

@spec get_mobile_number(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, Solaris.Error.t()}

Retrieves the registered mobile number for a person. Returns {:error, %Error{code: :not_found}} if none registered.

@spec get_tax_identification(String.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, Solaris.Error.t()}

Retrieves a specific tax identification.

@spec list(keyword()) :: {:ok, map()} | {:error, Solaris.Error.t()}

Lists all persons for the authenticated partner.

Options

• :page — page number
• :per_page — results per page (default: 10, max: 100)
• :after — cursor for next page
• :before — cursor for previous page

Examples

{:ok, persons} = Solaris.Onboarding.Persons.list()
{:ok, page} = Solaris.Onboarding.Persons.list(per_page: 50)

@spec list_authorized_persons(
  String.t(),
  keyword()
) :: {:ok, [map()]} | {:error, Solaris.Error.t()}

Lists authorized persons on a person's account.

@spec list_documents(
  String.t(),
  keyword()
) :: {:ok, [map()]} | {:error, Solaris.Error.t()}

Lists all documents for a person.

@spec list_identification_documents(
  String.t(),
  keyword()
) :: {:ok, [map()]} | {:error, Solaris.Error.t()}

Lists identification documents for a person.

@spec list_tax_identifications(
  String.t(),
  keyword()
) :: {:ok, [map()]} | {:error, Solaris.Error.t()}

Lists all tax identifications for a person.

@spec reauthorize_mobile_number(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, Solaris.Error.t()}

Requests a new 2FA challenge for the mobile number.

@spec remove_authorized_person(String.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, Solaris.Error.t()}

Removes an authorized person.

@spec set_language(String.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, Solaris.Error.t()}

Sets the preferred language for a person (overwrites previous).

Examples

{:ok, _} = Solaris.Onboarding.Persons.set_language("cper_123", "de")

@spec simulate_id_document_expiry(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, Solaris.Error.t()}

Sandbox only. Simulates an expired ID document for a person. Useful for testing re-identification flows.

@spec stream(keyword()) :: Enumerable.t()

Streams all persons across all pages.

Examples

Solaris.Onboarding.Persons.stream()
|> Stream.each(fn person -> IO.inspect(person["id"]) end)
|> Stream.run()

@spec update(String.t(), map(), keyword()) ::
  {:ok, map()} | {:error, Solaris.Error.t()}

Updates a person's attributes.

Updating a previously-set field triggers the change-request SCA flow. A 202 response includes change_request_id — this must be completed via Solaris.Onboarding.ChangeRequests before changes take effect.

Examples

{:ok, result} = Solaris.Onboarding.Persons.update("cper_123", %{
  email: "new@example.com"
})

@spec update_document(String.t(), String.t(), map(), keyword()) ::
  {:ok, map()} | {:error, Solaris.Error.t()}

Updates document attributes.

@spec update_tax_identification(String.t(), String.t(), map(), keyword()) ::
  {:ok, map()} | {:error, Solaris.Error.t()}

Updates a tax identification.

@spec upload_document(String.t(), binary(), keyword()) ::
  {:ok, map()} | {:error, Solaris.Error.t()}

Uploads a document for a person (multipart/form-data).

Options

• :document_type — e.g. "BANK_STATEMENT", "TAX_CERTIFICATE", "OTHER"
• :customer_accessible — boolean (default: false)
• :filename — original file name
• :content_type — MIME type (default: "application/octet-stream")

Examples

{:ok, doc} = Solaris.Onboarding.Persons.upload_document(
  "cper_123",
  File.read!("statement.pdf"),
  document_type: "BANK_STATEMENT",
  filename: "statement.pdf",
  content_type: "application/pdf"
)

@spec upload_identification_document(String.t(), binary(), keyword()) ::
  {:ok, map()} | {:error, Solaris.Error.t()}

Uploads an identification document (e.g. passport, ID card) for a person.

Identification documents are distinct from general documents — they are used specifically for KYC/AML verification and are stored separately.

Options

• :document_type — e.g. "PASSPORT", "NATIONAL_ID_CARD", "DRIVERS_LICENSE"

• :side — "front" | "back" (for two-sided documents)

• :filename, :content_type

Examples

{:ok, doc} = Solaris.Onboarding.Persons.upload_identification_document(
  "cper_123",
  File.read!("passport.jpg"),
  document_type: "PASSPORT",
  side: "front",
  filename: "passport_front.jpg",
  content_type: "image/jpeg"
)