### Beneficiary Attributes

| Attribute | Type | Definition | Example |
| --- | --- | --- | --- |
| id | UUID | the id of the beneficiary | a9d0164d-22df-46c6-a836-1a3da5a470d8 |
| entity | Entity | the entity object - NOT editable after creation | see entity schema |
| creator | UserAccount | the user object that created the beneficiary - NOT editable after creation | see UserAccount schema |
| type | String | the classification of the beneficiary, can either be 'personal' or 'business' - NOT editable after creation | personal |
| email | Email | email used for notification | [info@customer.com](mailto:info@customer.com) |
| phone | String | phone number of beneficiary | 9177234464 |
| phone_country | String | 2 letter ISO code of the country the phone number exists in | US |
| tax_number | TaxNumber | tax number of the beneficiary for the country provided | 121904576 |
| first_name | String | first name of the beneficiary | Thomas |
| last_name | String | last name of the beneficiary | Jones |
| address1 | String | address line 1 of beneficiary | 1305 E 6th St. |
| address2 | String | address line 2 of beneficiary | Unit 10 |
| city | String | city the beneficiary resides in | Austin |
| state_province_region | String | the state (US), province, or region the beneficiary resides in | Texas |
| postal_code | String | the postal code of the beneficiary | 78702 |
| country | String! | 2 letter ISO code of the country the beneficiary resides in | US |
| tax_number | String | the tax number of the beneficiary, this is only required for some countries | 111564839 |
| contact_first_name | String | first name of the contact of the beneficiary (business only) | George |
| contact_last_name | String | last name of the contact of the beneficiary (business only) | Castanza |
| business_name | String | name of business receiving payment | Routefusion |
| name_on_bank_account | String | legal owner of the bank account | Thomas Jones |
| swift_bic | String | SWIFT/BIC code of the bank; this can be an account number, CLABE or IBAN | CITIUS33XXX |
| account_type | AccountType | type of the beneficiaries account, can only be checking or saving | checking |
| account_number | String | the IBAN, CLABE, or account number of the bank account | 2345366452 |
| routing_code | String | routing code of the local financial system | A bank routing code |
| currency | String | the 3 character code of the currency - NOT editable after creation | USD |
| bank_name | String | the name of the banking institution | Citibank |
| branch_name | String | the name of the bank branch | LOS ANGELES-BRENTWOOD |
| bank_address1 | String | line 1 of the bank address | 11726 SAN VICENTE BLVD |
| bank_address2 | String | line 2 of the bank address | Unit 10 |
| bank_city | String | the city the bank is located | Los Angeles |
| bank_state_province_region | String | the state, region, or province the bank resides in | California |
| bank_postal_code | PostalCode | the postal code of the bank | 90049 |
| bank_country | ISO3166_1! | the 2 character country code the bank resides in - NOT editable after creation | US |
| changes_required | [String] | list of attributes that need to be updated |  |

#### GraphQL Schema

```graphql
enum BeneficiaryType {
  personal
  business
}

enum BeneficiaryState {
  accepted
  pending
  verified
  failed
}

enum VariableSubType {
  account_number
  iban
  clabe
  routing_number
  bank_code
  bsb
  anm
  bn_qst
  br
  cif
  cn_rn
  cnpj_cpf
  ein
  frp_tin_sst
  gst
  gst_uen
  kpp
  npwp
  rfc
  tin
  trn
  vat
}

enum AccountType {
  checking
  saving
}

type Beneficiary {
  id: UUID!
  entity: Entity!
  creator: UserAccount
  type: BeneficiaryType!
  state: BeneficiaryState
  email: Email!
  phone: String
  phone_country: String
  tax_number: TaxNumber

first_name: String
  last_name: String
  address1: String
  address2: String
  city: String
  state_province_region: String
  postal_code: PostalCode
  country: ISO3166_1

contact_first_name: String
  contact_last_name: String
  business_name: String

name_on_bank_account: String
  swift_bic: SwiftBic
  account_number: BankAccountNumber
  account_type: AccountType
  routing_code: BankRoutingCode
  currency: ISO4217!
  bank_name: String
  branch_name: String
  bank_address1: String
  bank_address2: String
  bank_city: String
  bank_state_province_region: String
  bank_postal_code: PostalCode
  bank_country: ISO3166_1!
  created_date: DateTime
}

type ValidBankCodes {
  code: String
  bank_name: String
  swift_bic: String
}

type BeneficiaryRequiredFieldsItem {
  variable: String
  regex: String
  variable_sub_type: VariableSubType
  example: String
  enum: [String]
  valid_bank_codes: [ValidBankCodes]
}

type BeneficiaryRequiredFields {
  personal: [BeneficiaryRequiredFieldsItem]
  business: [BeneficiaryRequiredFieldsItem]
}

type BeneficiaryPage {
  items: [Beneficiary]
  pagination: Pagination
}

type Pagination {
  page: Int
  page_size: Int
  pages_total: Int
  items_total: Int
}

type FilterInput {
  key: String
  values: [String]
  value: Boolean
}

type PaginationInput {
  page: Int = 1
  page_size: Int = 20
}

type Query {
  # get beneficiary
  beneficiary(
    beneficiary_id: UUID!
  ): Beneficiary

# get all organization beneficiaries
  organizationBeneficiaries(
    search_terms: String # optional
    listFilter: ListFilter
  ): [Beneficiary]

# get all users beneficiaries
  userBeneficiaries(
    user_id: UUID!
    search_terms: String # optional
    listFilter: ListFilter
  ): [Beneficiary]

# get all entity beneficiaries
  entityBeneficiaries(
    entity_id: UUID!
    search_terms: String # optional
    listFilter: ListFilter
  ): [Beneficiary]

# get all required fields for beneficiary creation
  beneficiaryRequiredFields(
    bank_country: ISO3166_1!
    currency: ISO4217!
    beneficiary_country: ISO3166_1
  ): BeneficiaryRequiredFields

beneficiariesPage(
    search_terms: String
    pagination: PaginationInput!
    filters: [FilterInput]
  ): BeneficiaryPage
}

type Mutation {
  # create personal beneficiary (must have a verified entity)
  createPersonalBeneficiary(
    user_id: UUID!
    entity_id: UUID!

email: Email!
    phone: String
    phone_country: String
    first_name: String!
    last_name: String!
    address1: String
    address2: String
    city: String
    state_province_region: String
    postal_code: PostalCode
    country: ISO3166_1!
    tax_number: TaxNumber

name_on_bank_account: String
    swift_bic: SwiftBic
    account_type: AccountType
    # this can be account number, clabe or iban
    account_number: BankAccountNumber
    # this can be routing number, sort code or bank code, bsb
    routing_code: BankRoutingCode
    currency: ISO4217!
    bank_name: String
    # only required for some countries
    branch_name: String
    bank_address1: String
    bank_address2: String
    bank_city: String
    bank_state_province_region: String
    bank_postal_code: PostalCode
    bank_country: ISO3166_1!
  ): UUID

# create business beneficiary (must have a verified entity)
  createBusinessBeneficiary(
    user_id: UUID!
    # must be verified
    entity_id: UUID!

email: Email!
    phone: String
    phone_country: String
    business_name: String!
    business_address1: String
    business_address2: String
    business_city: String
    business_state_province_region: String
    business_postal_code: PostalCode
    business_country: ISO3166_1!
    tax_number: TaxNumber

name_on_bank_account: String
    swift_bic: SwiftBic
    # this can be account number, clabe or iban
    account_number: BankAccountNumber
    account_type: AccountType # this can be checking or saving
    # this can be routing number, sort code or bank code
    routing_code: BankRoutingCode
    currency: ISO4217!
    bank_name: String
    # only required for some countries
    branch_name: String
    bank_address1: String
    bank_address2: String
    bank_city: String
    bank_state_province_region: String
    bank_postal_code: PostalCode
    bank_country: ISO3166_1!
  ): UUID
}
```