Railsr.Resources.Endusers (Railsr v1.0.0)

Railsr Enduser API — v2.

An enduser represents a person or business in your product. The typical lifecycle is: create → KYC check → activate → create ledger / card.

All functions return {:ok, struct} or {:error, %Railsr.Error{}}.

Enduser Statuses

"missing-doc" — awaiting KYC documents
"pending" — KYC in progress
"active" — KYC passed, can hold ledgers/cards
"suspended" — temporarily restricted
"declined" — KYC failed permanently

Example

{:ok, eu} = Railsr.Resources.Endusers.create(%{
  person: %{
    name: %{family_name: "Smith", given_name: "Alice"},
    email: "alice@example.com",
    date_of_birth: "1990-01-15",
    nationality: "GB",
    country_of_residence: ["GB"],
    address: %{
      address_number: "14",
      address_street: "High Street",
      address_city: "London",
      address_postal_code: "EC1A 1BB",
      address_iso_country: "GB"
    }
  }
})

Summary

Functions

create(params, opts \\ [])

Create a new enduser (person or company).

create_kyc_check(enduser_id, params \\ %{}, opts \\ [])

Trigger a KYC check for an enduser.

get(enduser_id, opts \\ [])

Retrieve a single enduser by ID.

get_kyc_check(enduser_id, check_id, opts \\ [])

Get the result of a specific KYC check.

list(query \\ %{}, opts \\ [])

List endusers.

list_kyc_checks(enduser_id, opts \\ [])

List all KYC checks for an enduser.

patch(enduser_id, params, opts \\ [])

Partial update of an enduser (PATCH semantics — only provided fields changed).

recalculate_firewall(enduser_id, opts \\ [])

Manually re-run the compliance firewall calculation for an enduser.

update(enduser_id, params, opts \\ [])

Full update of an enduser (PUT semantics — all fields replaced).

wait_for_status(enduser_id, target_statuses, opts \\ [])

Poll until an enduser reaches one of the given statuses, or timeout.

Functions

create(params, opts \\ [])

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

Create a new enduser (person or company).

Pass either a :person or :company key in params.

create_kyc_check(enduser_id, params \\ %{}, opts \\ [])

@spec create_kyc_check(String.t(), map(), keyword()) ::
  {:ok, Railsr.Types.KycCheck.t()} | {:error, Railsr.Error.t()}

Trigger a KYC check for an enduser.

The check runs asynchronously; listen for enduser-kyc-passed or enduser-kyc-failed webhooks, or poll list_kyc_checks/2.

get(enduser_id, opts \\ [])

@spec get(
  String.t(),
  keyword()
) :: {:ok, Railsr.Types.Enduser.t()} | {:error, Railsr.Error.t()}

Retrieve a single enduser by ID.

get_kyc_check(enduser_id, check_id, opts \\ [])

@spec get_kyc_check(String.t(), String.t(), keyword()) ::
  {:ok, Railsr.Types.KycCheck.t()} | {:error, Railsr.Error.t()}

Get the result of a specific KYC check.

list(query \\ %{}, opts \\ [])

@spec list(
  map(),
  keyword()
) :: {:ok, [Railsr.Types.Enduser.t()]} | {:error, Railsr.Error.t()}

List endusers.

Query params (all optional)

:status — filter by status string
:from / :to — ISO 8601 datetime bounds
:limit / :offset — pagination

list_kyc_checks(enduser_id, opts \\ [])

@spec list_kyc_checks(
  String.t(),
  keyword()
) :: {:ok, [Railsr.Types.KycCheck.t()]} | {:error, Railsr.Error.t()}

List all KYC checks for an enduser.

patch(enduser_id, params, opts \\ [])

@spec patch(String.t(), map(), keyword()) ::
  {:ok, Railsr.Types.Enduser.t()} | {:error, Railsr.Error.t()}

Partial update of an enduser (PATCH semantics — only provided fields changed).

recalculate_firewall(enduser_id, opts \\ [])

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

Manually re-run the compliance firewall calculation for an enduser.

update(enduser_id, params, opts \\ [])

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

Full update of an enduser (PUT semantics — all fields replaced).

wait_for_status(enduser_id, target_statuses, opts \\ [])

@spec wait_for_status(String.t(), [String.t()], keyword()) ::
  {:ok, Railsr.Types.Enduser.t()} | {:error, :timeout | Railsr.Error.t()}

Poll until an enduser reaches one of the given statuses, or timeout.

Options

:timeout_ms — total wait timeout in ms (default: 120_000)
:poll_ms — polling interval in ms (default: 2_000)

Returns {:ok, enduser} when the target status is reached, {:error, :timeout} if the deadline passes, or {:error, error} on any API error.