Beneficiaries

A beneficiary represents a destination to which funds may be transferred. they may include various types of external accounts such as other banks, wire transfers, Paypal, etc. The API calls at this endpoint manage beneficiaries.

The elements of the record describing each beneficiary depend on the transaction type to be used with that destination. The transaction type is identified by the element txnType.

Beneficiary Object

AmpliFi represents a beneficiary by a JSON object. Some of the properties of this object depend on the transaction type for that beneficiary. The properties that may appear in a beneficiary object are shown in the following table.

Property	Type	Required? (default)	Description
AFiBeneficiaryId	string	yes	AmpliFi Id of the beneficiary
AFiUserId	string	yes	Id of the current user
name	string	yes	name for the beneficiary
defaultAmount	number	no (none)	default transfer amount, if any
defaultCurrency	string	no (none)	3-letter currency designator for default amount; required if default amount present
txnType	string	yes	type of transaction for this beneficiary (see below)
typeName
type	string	no (none)	type of account, if applicable
destinationName	string	no (none)	name on the destination account, for USA ACH and USA and international wire transfers
bankName	string	yes	name of the destination bank, for USA ACH and wire transfers
routingNumber	number	no (none)	destination routing number, for USA ACH and wire transfers
accountNumber	number	no (none)	destination account number, for USA ACH and wire transfers
bic	string	no (none)	bank id Code for international wire transfers
iban	string	no (none)	International Bank Account Id for international wire transfers
paypalId	string	no (none)	PayPal Id, for PayPal transfers
destinationPAN	string	no (none)	Permanent Account Number, for card transfers
address	object	no (none)	address object, for paper checks (see below)
status	string	yes	"active" or ??
dtsCreated	dts	yes	date/time beneficiary was created
isActive	boolean	yes	true if the beneficiary is active
isFavourite	boolean	no (false)	true if the beneficiary is designated a favorite
isDeleted	boolean	no (false)	true if the beneficiary has been deleted

address object:

Property	Type	Required? (default)	Description
type	string	yes	address type ("PRIMARY" or "SECONDARY")
addressLine1	string	yes	street address
addressLine2	string	no (none)	remainder of address, if any
city	string	yes	city
state	string	no (none)	2-letter state or province code, if any
postalCode	string	no (none)	zip or postal code, if any
country	string	yes	2-letter country code, ISO 3166-1 alpha-2 format

Possible transaction types, with their corresponding properties, are:

txnType	Properties	Description
USA	bankName, detinationName, type, routingNumber, account Number	ACH transfer within the US
USA_wire	bankName, detinationName, type, routingNumber, account Number	Wire transfer within the US
international	bic, iban	Cross-border wire via SWIFT
paypal	paypalId	Tranfer to PayPal
tocard	destinationPAN	Push-to-card
cheque	address	Paper check mailed via USPS

Examples

USA ACH or wire transfer beneficiary:

{
  "AFiBeneficiaryId": "ampbenkssaqqbowkelwyxlyl",
  "AFiUserId": "aurksrrlqe8uu",
  "name": "My landlord",
  "defaultAmount": 0,
  "defaultCurrency": "USD",
  "txnType": "USA",
  "bankName": "Citi",
  "destinationName": "John Doe",
  "routingNumber": "123123123",
  "accountNumber": "123456789",
  "type": "CHECKING",
  "status": "active",
  "dtsCreated": "2021-08-26T02:18:03.588Z",
  "isActive": true,
  "isFavourite": true
  "isDeleted": false,
}

International wire transfer beneficiary:

{
  "AFiBeneficiaryId": "ampbenkssaqqbowkelwyxlyl",
  "AFiUserId": "aurksrrlqe8uu",
  "name": "My landlord",
  "defaultAmount": 0,
  "defaultCurrency": "USD",
  "txnType": "international",
  "destinationName": "John Doe",
  "bic": "AEIBCHGV" //Bank ID
  "iban": "AE630030000701063132001", //full IBAN
  "status": "active",
  "dtsCreated": "2021-08-26T02:18:03.588Z",
  "isActive": true,
  "isFavourite": true
  "isDeleted": false,
}

Card transfer beneficiary:

{
  "AFiBeneficiaryId": "ampbenkssaqqbowkelwyxlyl",
  "AFiUserId": "aurksrrlqe8uu",
  "name": "My landlord",
  "txnType": "international",
  "destinationPAN": "1234567890123456" //Full card number
  "status": "active",
  "dtsCreated": "2021-08-26T02:18:03.588Z",
  "isActive": true,
}

Paper check beneficiary:

{
  "AFiBeneficiaryId": "ampbenkssaqqbowkelwyxlyl",
  "AFiUserId": "aurksrrlqe8uu",
  "name": "My landlord",
  "txnType": "international",
  "address": {
      "addressLine1": "123 Main str",
      "addressLine2": "Apt 1",
      "city": "Harrisburg",
      "state": "PA",
      "country": "US",
      "postalCode": "12345"
  }
  "status": "active",
  "dtsCreated": "2021-08-26T02:18:03.588Z",
  "isActive": true,
}

Get Beneficiaries

Returns an array of records for all beneficiaries registered for the current user. Only the last 4 digits of the account number (if any) are returned.

GET /beneficiaries

Response body:

{
  "success": true,
  "beneficiaries": [ // array of beneficiary objects
  ]
}

Add Beneficiary

PUT /beneficiaries

Add a beneficiary for the current user. The required and optional properties of the request depend on the transaction type.

Request body example:

  {
    "txnType": "USA",
    "name": "My landlord",
    ...
    (optional properties)
    (properties depending on txnType)
 }

Response body:

  {
  "success": true,
  "beneficiary": 
    { // beneficiary object
    }
  }

Modify Beneficiary

Makes changes to an existing beneficiary record. The beneficiary is identified by a path parameter. Only the elements that are actually changed should be included in the request body.

POST /beneficiary/:AFiBeneficiaryId

Request body example:

  {
    "txnType": "USA",
    "name": "My landlord",
        ...
    (properties to be changed or added)

  }

Response:

  {
    "success": true,
    "beneficiary": 
    { // modified beneficiary object
    }
  }

Delete Beneficiary

Deletes a beneficiary record. The beneficiary is identified by a path parameter. The user is no longer able to transfer funds to this beneficiary.

DELETE /beneficiary/:AFiBeneficiaryId

Response:

  {
    "success": true,
    "text": "queued the beneficiary deletion"
  }