Skip to content

Add Beneficiary

Request URL

PUT /beneficiaries

Description

This endpoint will add a beneficiary for the current user. The ampliFi API represents a beneficiary by a JSON object. Some properties of this object depend on the transaction type for that beneficiary. The transaction type is identified by the element txnType. If included in the request, the country code will be in ISO 3166-1 alpha-2 format.

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

Schema

Property table for address object

Property Description Required Schema
type Entity type No {
  "type": "string",
  "enum": [ "PRIMARY", "SECONDARY" ],
  "nullable": true
}
addressLine1 addressLine1 Yes {
  "type": "string"
}
addressLine2 addressLine2 No {
  "type": "string",
  "nullable": true
}
city city Yes {
  "type": "string"
}
state state No {
  "type": "string",
  "nullable": true,
  "minLength": 2,
  "maxLength": 2
}
province province Yes {
  "type": "string"
}
postalCode postalCode Yes {
  "type": "string"
}
country Country code No {
  "type": "string",
  "nullable": true,
  "minLength": 2,
  "maxLength": 2
}

Property table for country object

Property Description Required Schema
code code No {
  "type": "string"
}

Property table for schema 1 for beneficiaries

Property Description Required Schema
txnType Type of transaction Yes {
  "type": "string",
  "enum": [ "USA", "USA_wire" ]
}
name Name of the entity No {
  "type": "string",
  "nullable": true
}
defaultAmount Default transfer amount No {
  "type": "number",
  "nullable": true,
  "default": 0
}
defaultCurrency 3-letter currency designator for default amount No {
  "type": "string",
  "nullable": true,
  "default": "USD"
}
isFavorite isFavorite No {
  "type": "boolean",
  "nullable": true,
  "default": false
}
isDeleted true if deleted No {
  "type": "boolean",
  "nullable": true,
  "default": false
}
routingNumber Routing number Yes {
  "type": "string",
  "minLength": 9,
  "maxLength": 9
}
accountNumber Account number No {
  "type": "string"
}
bankName Name of the bank Yes {
  "type": "string"
}
type Entity type Yes {
  "type": "string",
  "enum": [ "CHECKING", "SAVINGS" ]
}
destinationName Name on the destination account Yes {
  "type": "string"
}

Property table for schema 2 for beneficiaries

Property Description Required Schema
txnType Type of transaction Yes {
  "type": "string",
  "enum": [ "international" ]
}
name Name of the entity No {
  "type": "string",
  "nullable": true
}
defaultAmount Default transfer amount No {
  "type": "number",
  "nullable": true,
  "default": 0
}
defaultCurrency 3-letter currency designator for default amount No {
  "type": "string",
  "nullable": true,
  "default": "USD"
}
isFavorite isFavorite No {
  "type": "boolean",
  "nullable": true,
  "default": false
}
isDeleted true if deleted No {
  "type": "boolean",
  "nullable": true,
  "default": false
}
bic Bank ID Code for international wire transfers Yes {
  "type": "string"
}
iban International Bank Account ID for international wire transfers Yes {
  "type": "string"
}

Property table for schema 3 for beneficiaries

Property Description Required Schema
txnType Type of transaction Yes {
  "type": "string",
  "enum": [ "paypal" ]
}
name Name of the entity No {
  "type": "string",
  "nullable": true
}
defaultAmount Default transfer amount No {
  "type": "number",
  "nullable": true,
  "default": 0
}
defaultCurrency 3-letter currency designator for default amount No {
  "type": "string",
  "nullable": true,
  "default": "USD"
}
isFavorite isFavorite No {
  "type": "boolean",
  "nullable": true,
  "default": false
}
isDeleted true if deleted No {
  "type": "boolean",
  "nullable": true,
  "default": false
}
paypalId PayPal ID, for PayPal transfers Yes {
  "type": "string"
}

Property table for schema 4 for beneficiaries

Property Description Required Schema
txnType Type of transaction Yes {
  "type": "string",
  "enum": [ "2" ]
}
name Name of the entity No {
  "type": "string",
  "nullable": true
}
defaultAmount Default transfer amount No {
  "type": "number",
  "nullable": true,
  "default": 0
}
defaultCurrency 3-letter currency designator for default amount No {
  "type": "string",
  "nullable": true,
  "default": "USD"
}
isFavorite isFavorite No {
  "type": "boolean",
  "nullable": true,
  "default": false
}
isDeleted true if deleted No {
  "type": "boolean",
  "nullable": true,
  "default": false
}
accountNumber Account number Yes {
  "type": "string"
}

Property table for schema 5 for beneficiaries

Property Description Required Schema
txnType Type of transaction Yes {
  "type": "string",
  "enum": [ "westernunion" ]
}
name Name of the entity No {
  "type": "string",
  "nullable": true
}
defaultAmount Default transfer amount No {
  "type": "number",
  "nullable": true,
  "default": 0
}
defaultCurrency 3-letter currency designator for default amount No {
  "type": "string",
  "nullable": true,
  "default": "USD"
}
isFavorite isFavorite No {
  "type": "boolean",
  "nullable": true,
  "default": false
}
isDeleted true if deleted No {
  "type": "boolean",
  "nullable": true,
  "default": false
}
country Country code Yes country object
firstName First name Yes {
  "type": "string"
}
lastName Last name Yes {
  "type": "string"
}

Property table for schema 6 for beneficiaries

Property Description Required Schema
txnType Type of transaction Yes {
  "type": "string",
  "enum": [ "tocard" ]
}
name Name of the entity No {
  "type": "string",
  "nullable": true
}
defaultAmount Default transfer amount No {
  "type": "number",
  "nullable": true,
  "default": 0
}
defaultCurrency 3-letter currency designator for default amount No {
  "type": "string",
  "nullable": true,
  "default": "USD"
}
isFavorite isFavorite No {
  "type": "boolean",
  "nullable": true,
  "default": false
}
isDeleted true if deleted No {
  "type": "boolean",
  "nullable": true,
  "default": false
}
destinationPAN PAN, for cards Yes {
  "type": "string"
}
expiryYYYYMM Expiration date Yes {
  "type": "string"
}
destinationFirstName First name on the destination account Yes {
  "type": "string"
}
destinationLastName Last name on the destination account Yes {
  "type": "string"
}

Property table for schema 7 for beneficiaries

Property Description Required Schema
txnType Type of transaction Yes {
  "type": "string",
  "enum": [ "cheque" ]
}
name Name of the entity No {
  "type": "string",
  "nullable": true
}
defaultAmount Default transfer amount No {
  "type": "number",
  "nullable": true,
  "default": 0
}
defaultCurrency 3-letter currency designator for default amount No {
  "type": "string",
  "nullable": true,
  "default": "USD"
}
isFavorite isFavorite No {
  "type": "boolean",
  "nullable": true,
  "default": false
}
isDeleted true if deleted No {
  "type": "boolean",
  "nullable": true,
  "default": false
}
legalName Legal name of the beneficiary Yes {
  "type": "string"
}
address Address details Yes address object

Request Body

{
    "name": "Test", 
    "txnType": "cheque",
    "amount": 0, 
    "currency": "USD",
    "legalName": "John Doe",
    "address": {
      "addressLine1": "123 Main str",
      "addressLine2": "Apt 1",
      "city": "Harrisburg",
      "province": "Pennsylvania",
      "postalCode": "17025"
    }
}

Snippet Examples

javascript

const axios = require('axios');
const data = {
    "name": "Test", 
    "txnType": "cheque",
    "amount": 0, 
    "currency": "USD",
    "legalName": "John Doe",
    "address": {
      "addressLine1": "123 Main str",
      "addressLine2": "Apt 1",
      "city": "Harrisburg",
      "province": "Pennsylvania",
      "postalCode": "17025"
    }
}
;
const config = {
  method: 'PUT',
  url: '${AMPLIFI_BASE_URL}/beneficiaries',
  headers: {
    'Content-Type': "application/json",
    'token': "A long random string token received from /token request"
  },
  data
};

let result;
try {
  result = await axios.request(config);
  if (result.status === 200) {
    console.log(JSON.stringify(result.data));
  }
} catch (err) {
  console.log({
    errCode: err.code,
    responseStatus: err.response && err.response.status,
    data: err.response && JSON.stringify(err.response.data)
  });
}

cURL

curl --location "AMPLIFI_BASE_URL/beneficiaries" --data "{    \"name\":\"Test\",    \"txnType\":\"cheque\",   \"amount\":0,    \"currency\":\"USD\",   \"legalName\":\"John Doe\",   \"address\":{      \"addressLine1\":\"123 Main str\",     \"addressLine2\":\"Apt 1\",     \"city\":\"Harrisburg\",     \"province\":\"Pennsylvania\",     \"postalCode\":\"17025\"    }}" --header "Content-Type: application/json" --header "token: A long random string token received from /token request"

Successful Response Examples

200 BENEFICIARIES SUCCESSFUL RESPONSE ADDING USA ACH BENEFICIARY 1

HEADERS

Header Value
Content-Type application/json
token A long random string token received from /token request

REQUEST BODY

{
    "name": "Test8ACH", 
    "txnType": "USA",
    "routingNumber": "031101279",
    "accountNumber": "12345678903214",
    "amount": 1.01, 
    "currency": "USD",
    "bankName": "Citi",
    "type": "CHECKING",
    "country": "USA",
    "destinationName": "John Doe",
    "accountTitle": "John Doe1",
    "address": {
      "addressLine1": "123 Main str",
      "addressLine2": "Apt 1",
      "city": "Harrisburg",
      "state": "PA",
      "province": "Pennsylvania",
      "countryCode": "+1",
      "postalCode": "12345"
    }
}

RESPONSE BODY

{
    "success": true,
    "beneficiary": {
        "name": "Test8ACH",
        "txnType": "USA",
        "routingNumber": "031101279",
        "accountNumber": "***3214",
        "amount": 1.01,
        "currency": "USD",
        "bankName": "The Bancorp Bank National Association",
        "type": "CHECKING",
        "country": "USA",
        "destinationName": "John Doe",
        "accountTitle": "John Doe1",
        "address": {
            "addressLine1": "123 Main str",
            "addressLine2": "Apt 1",
            "city": "Harrisburg",
            "state": "PA",
            "province": "Pennsylvania",
            "countryCode": "+1",
            "postalCode": "12345"
        },
        "typeName": "USA interbank transfer",
        "logoB64": "data:image/jpeg;base64,a+very+long+b64+encoded_string",
        "AFiBeneficiaryId": "qwepgbenlq15j9s8sw",
        "defaultAmount": 0,
        "dtsCreated": "2023-12-11T16:52:30.152Z",
        "status": "Pending",
        "userId": "qweaurl8kgtlv9pc",
        "AFiUserId": "qweaurl8kgtlv9pc",
        "isDeleted": false,
        "isFavourite": true
    }
}

200 BENEFICIARIES SUCCESSFUL RESPONSE ADDING USA ACH BENEFICIARY 2

HEADERS

Header Value
Content-Type application/json
token A long random string token received from /token request

REQUEST BODY

{
    "txnType": "USA",
    "routingNumber": "031101279",
    "accountNumber": "12345678903217",
    "bankName": "Citi",
    "type": "CHECKING",
    "destinationName": "John Doe"
}

RESPONSE BODY

{
    "success": true,
    "beneficiary": {
        "txnType": "USA",
        "routingNumber": "031101279",
        "accountNumber": "***3217",
        "bankName": "The Bancorp Bank National Association",
        "type": "CHECKING",
        "destinationName": "John Doe",
        "typeName": "USA interbank transfer",
        "logoB64": "data:image/jpeg;base64,a+very+long+b64+encoded_string",
        "AFiBeneficiaryId": "qwepgbenlq1le3opti",
        "defaultAmount": 0,
        "dtsCreated": "2023-12-12T00:16:22.825Z",
        "status": "Pending",
        "userId": "qweaurl8kgtlv9pc",
        "AFiUserId": "qweaurl8kgtlv9pc",
        "isDeleted": false,
        "isFavourite": true,
        "backOffices": [
            {
                "backOfficeId": "evolve",
                "backOfficeName": "evolve",
                "AFiBeneficiaryId": "qwepgbenlq1le3opti"
            }
        ]
    }
}

200 BENEFICIARIES SUCCESSFUL RESPONSE ADDING USA_WIRE BENEFICIARY

HEADERS

Header Value
Content-Type application/json
token A long random string token received from /token request

REQUEST BODY

{
    "name": "Test9Wire", 
    "txnType": "USA_wire",
    "routingNumber": "031101279",
    "accountNumber": "12345678903215",
    "amount": 0, 
    "currency": "USD",
    "bankName": "Citi",
    "type": "CHECKING",
    "country": "USA",
    "destinationName": "John Doe",
    "accountTitle": "John Doe1",
    "address": {
      "addressLine1": "123 Main str",
      "addressLine2": "Apt 1",
      "city": "Harrisburg",
      "state": "PA",
      "province": "Pennsylvania",
      "countryCode": "+1",
      "postalCode": "12345"
    }
}

RESPONSE BODY

{
    "success": true,
    "beneficiary": {
        "name": "Test9Wire",
        "txnType": "USA_wire",
        "routingNumber": "031101279",
        "accountNumber": "***3215",
        "amount": 0,
        "currency": "USD",
        "bankName": "The Bancorp Bank National Association",
        "type": "CHECKING",
        "country": "USA",
        "destinationName": "John Doe",
        "accountTitle": "John Doe1",
        "address": {
            "addressLine1": "123 Main str",
            "addressLine2": "Apt 1",
            "city": "Harrisburg",
            "state": "PA",
            "province": "Pennsylvania",
            "countryCode": "+1",
            "postalCode": "12345"
        },
        "typeName": "USA interbank transfer",
        "logoB64": "data:image/jpeg;base64,a+very+long+b64+encoded_string",
        "AFiBeneficiaryId": "qwepgbenlq1620trhs",
        "defaultAmount": 0,
        "dtsCreated": "2023-12-11T17:07:05.007Z",
        "status": "Pending",
        "userId": "qweaurl8kgtlv9pc",
        "AFiUserId": "qweaurl8kgtlv9pc",
        "isDeleted": false,
        "isFavourite": true,
        "backOffices": [
            {
                "backOfficeId": "evolve",
                "backOfficeName": "evolve",
                "AFiBeneficiaryId": "qwepgbenlq1620trhs"
            }
        ]
    }
}

200 BENEFICIARIES SUCCESSFUL RESPONSE ADDING CARD BENEFICIARY 1

HEADERS

Header Value
Content-Type application/json
token A long random string token received from /token request

REQUEST BODY

{
    "name": "Test15Card", 
    "txnType": "tocard",
    "amount": 0, 
    "currency": "USD",
    "destinationPAN": "1234567890123456",
    "expiryYYYYMM": "202610",
    "destinationFirstName": "John",
    "destinationLastName": "Doe"
}

RESPONSE BODY

{
    "success": true,
    "beneficiary": {
        "name": "Test15Card",
        "txnType": "tocard",
        "amount": 0,
        "currency": "USD",
        "destinationPAN": "1234567890123456",
        "expiryYYYYMM": "202610",
        "destinationFirstName": "John",
        "destinationLastName": "Doe",
        "typeName": "Card",
        "AFiBeneficiaryId": "qwepgbenlq1k3cv1ao",
        "defaultAmount": 0,
        "dtsCreated": "2023-12-11T23:40:01.885Z",
        "status": "Pending",
        "isActive": false,
        "userId": "qweaurl8kgtlv9pc",
        "AFiUserId": "qweaurl8kgtlv9pc",
        "isDeleted": false,
        "isFavourite": true,
        "backOffices": [
            {
                "backOfficeId": "evolve",
                "backOfficeName": "evolve",
                "AFiBeneficiaryId": "qwepgbenlq1k3cv1ao",
                "beneficiaryIdBO": "DagK-ErE2U6GDNNiOjxIPg"
            }
        ]
    }
}

200 BENEFICIARIES SUCCESSFUL RESPONSE ADDING CARD BENEFICIARY 2

HEADERS

Header Value
Content-Type application/json
token A long random string token received from /token request

REQUEST BODY

{
    "name": "Test15Card", 
    "txnType": "tocard",
    "destinationPAN": "1234567890123456",
    "expiryYYYYMM": "202610",
    "destinationFirstName": "John",
    "destinationLastName": "Doe"
}

RESPONSE BODY

{
    "success": true,
    "beneficiary": {
        "name": "Test15Card",
        "txnType": "tocard",
        "destinationPAN": "1234567890123456",
        "expiryYYYYMM": "202610",
        "destinationFirstName": "John",
        "destinationLastName": "Doe",
        "typeName": "Card",
        "AFiBeneficiaryId": "qwepgbenlq1m1tnctv",
        "defaultAmount": 0,
        "dtsCreated": "2023-12-12T00:34:49.560Z",
        "status": "Pending",
        "isActive": false,
        "userId": "qweaurl8kgtlv9pc",
        "AFiUserId": "qweaurl8kgtlv9pc",
        "isDeleted": false,
        "isFavourite": true,
        "backOffices": [
            {
                "backOfficeId": "evolve",
                "backOfficeName": "evolve",
                "AFiBeneficiaryId": "qwepgbenlq1m1tnctv",
                "beneficiaryIdBO": "BeUL-xcVCeAYAbBTZNAdPw"
            }
        ]
    }
}

200 BENEFICIARIES SUCCESSFUL RESPONSE ADDING CHEQUE BENEFICIARY

HEADERS

Header Value
Content-Type application/json
token A long random string token received from /token request

REQUEST BODY

{
    "name": "Test", 
    "txnType": "cheque",
    "amount": 0, 
    "currency": "USD",
    "legalName": "John Doe",
    "address": {
      "addressLine1": "123 Main str",
      "addressLine2": "Apt 1",
      "city": "Harrisburg",
      "state": "PA",
      "province": "Pennsylvania",
      "countryCode": "+1",
      "postalCode": "12345"
    }
}

RESPONSE BODY

{
    "success": true,
    "beneficiary": {
        "name": "Test",
        "txnType": "cheque",
        "amount": 0,
        "currency": "USD",
        "legalName": "John Doe",
        "address": {
            "addressLine1": "123 Main str",
            "addressLine2": "Apt 1",
            "city": "Harrisburg",
            "state": "PA",
            "province": "Pennsylvania",
            "countryCode": "+1",
            "postalCode": "12345"
        },
        "typeName": "Paper check",
        "AFiBeneficiaryId": "qwepgbenlq1k96locu",
        "defaultAmount": 0,
        "dtsCreated": "2023-12-11T23:44:33.708Z",
        "status": "Pending",
        "userId": "qweaurl8kgtlv9pc",
        "AFiUserId": "qweaurl8kgtlv9pc",
        "isDeleted": false,
        "isFavourite": true,
        "backOffices": [
            {
                "backOfficeId": "evolve",
                "backOfficeName": "evolve",
                "AFiBeneficiaryId": "qwepgbenlq1k96locu"
            }
        ]
    }
}