Get beneficiary information

Get beneficiary information for a Swan International Credit Transfer.

Use the internationalBeneficiaryDynamicForms query to find out what information you'll need to include about your beneficiary, both in the transaction details query and when you initiate your transfer.

Example only

This example is for illustrative purposes only using United States Dollars (USD).

The required key/value pairs change based on currency, country, and route. Additionally, the pairs aren't controlled by Swan and can change without advance notice.

Step 1: Call query

1. Call the internationalBeneficiaryDynamicForms query.
2. Add required, non-dynamic information: enter the value and currency for amount, and optionally, choose a language.
3. Add all desired fields. Make sure to include remainingFieldsToRefreshCount for the whole query, plus refreshDynamicFieldsOnChange for each field type.

🔎 Open the query in API Explorer

Open to review the query to compile information for an international beneficiary

query BeneficiaryDynamicForm {
  internationalBeneficiaryDynamicForms(
    amount: { value: "500", currency: "USD" }
    language: en
  ) {
    schemes {
      type
      title
      remainingFieldsToRefreshCount
      fields {
        key
        name
        required
        ... on DateField {
          example
          validationRegex
          key
          name
          required
        }
        ... on RadioField {
          __typename
          key
          name
          refreshDynamicFieldsOnChange
          required
          allowedValues {
            key
            name
          }
        }
        ... on SelectField {
          __typename
          key
          name
          refreshDynamicFieldsOnChange
          required
          allowedValues {
            key
            name
          }
        }
        ... on TextField {
          displayFormat
          example
          key
          maxLength
          minLength
          name
          refreshDynamicFieldsOnChange
          required
          validationRegex
        }
      }
    }
  }
}

Step 2: Review first payload

The query example results in the following payload, which provides several key/value pairs.

partial payload

Note this is a partial payload (signaled by the ... on lines 6 and 118). It only includes the route type FedwireLocal to reduce the length, and country codes were removed and replaced with placeholders (lines 76-77). The full payload contains over 3,000 lines.

Objects in the API Explorer's secondary terminal (where you receive the payload) are collapsible, so consider collapsing sections of the payload that aren't relevant to your use case.

From this payload, note the following details:

1. Locate your desired route type. This excerpt shows FedwireLocal (line 10).
2. Locate remainingFieldsToRefreshCount to know how many dynamic fields you'll need to add in the next section (line 11).
3. Locate all required key/value pairs. This excerpt contains key/value pairs on lines 14, 31, 42, 53, 70, 83, 94, and 105:
   • legalType*
   • abartn
   • accountNumber
   • accountType
   • address.country*
   • address.city
   • address.firstLine
   • address.postCode
4. Identify key/value pairs where "refreshDynamicFieldsOnChange": true, needed for step 3 (lines 28, 80).

Open to review the first payload for your international beneficiary query

{
  "data": {
    "internationalBeneficiaryDynamicForms": {
      "schemes": [
        
        {...}
        
        {
          "title": "Wire",
          "type": "FedwireLocal"
          "remainingFieldsToRefreshCount": 2,
          "fields": [
            {
              "key": "legalType",
              "name": "Recipient type",
              "required": true,
              "__typename": "SelectField",
              "allowedValues": [
                {
                  "key": "PRIVATE",
                  "name": "Person"
                },
                {
                  "key": "BUSINESS",
                  "name": "Business"
                }
              ],
              "refreshDynamicFieldsOnChange": true
            },
            {
              "key": "abartn",
              "name": "Fedwire routing number",
              "required": true,
              "displayFormat": null,
              "example": "020123456",
              "maxLength": 9,
              "minLength": 9,
              "refreshDynamicFieldsOnChange": false,
              "validationRegex": "^\\d{9}$"
            },
            {
              "key": "accountNumber",
              "name": "Account number",
              "required": true,
              "displayFormat": null,
              "example": "12345678",
              "maxLength": 17,
              "minLength": 4,
              "refreshDynamicFieldsOnChange": false,
              "validationRegex": "^\\d{4,17}$"
            },
            {
              "key": "accountType",
              "name": "Account type",
              "required": true,
              "__typename": "RadioField",
              "allowedValues": [
                {
                  "key": "CHECKING",
                  "name": "Checking"
                },
                {
                  "key": "SAVINGS",
                  "name": "Savings"
                }
              ],
              "refreshDynamicFieldsOnChange": false
            },
            {
              "key": "address.country",
              "name": "Country",
              "required": true,
              "__typename": "SelectField",
              "allowedValues": [
                {
                  "key": "XX",
                  "name": "Country name"
                },
              ],
              "refreshDynamicFieldsOnChange": true
            },
            {
              "key": "address.city",
              "name": "City",
              "required": true,
              "displayFormat": null,
              "example": "",
              "maxLength": 255,
              "minLength": 1,
              "refreshDynamicFieldsOnChange": false,
              "validationRegex": "^.{1,255}$"
            },
            {
              "key": "address.firstLine",
              "name": "Recipient address",
              "required": true,
              "displayFormat": null,
              "example": "",
              "maxLength": 255,
              "minLength": 1,
              "refreshDynamicFieldsOnChange": false,
              "validationRegex": "^.{1,255}$"
            },
            {
              "key": "address.postCode",
              "name": "ZIP code",
              "required": true,
              "displayFormat": null,
              "example": "",
              "maxLength": 32,
              "minLength": 1,
              "refreshDynamicFieldsOnChange": false,
              "validationRegex": "^\\d{5}$"
            }
          ],
        },
        
        {...}
        
      ]
    }
  }
}

Step 3: Call query with updated dynamic fields

1. Call the internationalBeneficiaryDynamicForms query again.
2. Include the key/value pairs marked "refreshDynamicFieldsOnChange": true in your updated query.
   • In this example, the required fields to update are legalType and address.country (lines 6, 7).

🔎 Open the query in API Explorer

Open to review the updated query with required dynamic fields

query UpdateQuery {
  internationalBeneficiaryDynamicForms(
    amount: { value: "500", currency: "USD" }
    language: en
    dynamicFields: [
      { key: "legalType", value: "PRIVATE" }
      { key: "address.country", value: "US" }
    ]
  ) {
    schemes {
      type
      title
      remainingFieldsToRefreshCount
      fields {
        key
        name
        required
        ... on DateField {
          example
          validationRegex
          key
          name
          required
        }
        ... on RadioField {
          __typename
          key
          name
          refreshDynamicFieldsOnChange
          required
          allowedValues {
            key
            name
          }
        }
        ... on SelectField {
          __typename
          key
          name
          refreshDynamicFieldsOnChange
          required
          allowedValues {
            key
            name
          }
        }
        ... on TextField {
          displayFormat
          example
          key
          maxLength
          minLength
          name
          refreshDynamicFieldsOnChange
          required
          validationRegex
        }
      }
    }
  }
}

Step 4: Review second payload

This second query payload contains two important changes:

1. The remainingFieldsToRefreshCount now equals zero (line 11). This means you have all of the required key/value pairs and don't need to run the query again.
2. An additional required key/value pair appeared in the payload (line 105).
   • Because the address.country is US, the address.state is also required.
   • Additional key/value pairs can be added to the payload for all refreshable dynamic fields. This example only adds one key/value pair, but the quantity can change based on the information you provide.

partial payload

As with the payload in step 2, this is a partial payload (signaled by the ... on lines 6 and 132). It only includes the route type FedwireLocal to reduce the length, and country and state codes were removed and replaced with placeholders (lines 76-77, 112-113).

Open to review the second payload for your international beneficiary query

{
  "data": {
    "internationalBeneficiaryDynamicForms": {
      "schemes": [
        
        {...}
        
        {
          "type": "FedwireLocal",
          "title": "Wire",
          "remainingFieldsToRefreshCount": 0,
          "fields": [
            {
              "key": "legalType",
              "name": "Recipient type",
              "required": true,
              "__typename": "SelectField",
              "refreshDynamicFieldsOnChange": true,
              "allowedValues": [
                {
                  "key": "PRIVATE",
                  "name": "Person"
                },
                {
                  "key": "BUSINESS",
                  "name": "Business"
                }
              ]
            },
            {
              "key": "abartn",
              "name": "Fedwire routing number",
              "required": true,
              "displayFormat": null,
              "example": "020123456",
              "maxLength": 9,
              "minLength": 9,
              "refreshDynamicFieldsOnChange": false,
              "validationRegex": "^\\d{9}$"
            },
            {
              "key": "accountNumber",
              "name": "Account number",
              "required": true,
              "displayFormat": null,
              "example": "12345678",
              "maxLength": 17,
              "minLength": 4,
              "refreshDynamicFieldsOnChange": false,
              "validationRegex": "^\\d{4,17}$"
            },
            {
              "key": "accountType",
              "name": "Account type",
              "required": true,
              "__typename": "RadioField",
              "refreshDynamicFieldsOnChange": false,
              "allowedValues": [
                {
                  "key": "CHECKING",
                  "name": "Checking"
                },
                {
                  "key": "SAVINGS",
                  "name": "Savings"
                }
              ]
            },
            {
              "key": "address.country",
              "name": "Country",
              "required": true,
              "__typename": "SelectField",
              "refreshDynamicFieldsOnChange": true,
              "allowedValues": [
                {
                  "key": "XX",
                  "name": "Country name"
                }
              ]
            },
            {
              "key": "address.city",
              "name": "City",
              "required": true,
              "displayFormat": null,
              "example": "",
              "maxLength": 255,
              "minLength": 1,
              "refreshDynamicFieldsOnChange": false,
              "validationRegex": "^.{1,255}$"
            },
            {
              "key": "address.firstLine",
              "name": "Recipient address",
              "required": true,
              "displayFormat": null,
              "example": "",
              "maxLength": 255,
              "minLength": 1,
              "refreshDynamicFieldsOnChange": false,
              "validationRegex": "^.{1,255}$"
            },
            {
              "key": "address.state",
              "name": "State",
              "required": true,
              "__typename": "SelectField",
              "refreshDynamicFieldsOnChange": false,
              "allowedValues": [
                {
                  "key": "XX",
                  "name": "State name"
                }
              ]
            },
            {
              "key": "address.postCode",
              "name": "ZIP code",
              "required": true,
              "displayFormat": null,
              "example": "",
              "maxLength": 32,
              "minLength": 1,
              "refreshDynamicFieldsOnChange": false,
              "validationRegex": "^\\d{5}$"
            }
          ]
        },

        
        {...}
        
      ]
    }
  }
}

Step 5: Repeat

If remainingFieldsToRefreshCount is not equal to zero, repeat steps three and four to retrieve the rest of your required key/value pairs.

Repeat until "remainingFieldsToRefreshCount": 0.

Step 6: Compile beneficiary input

For the next query, you'll need to provide all of the key value pairs for your chosen route type.

Consider this beneficiary input example using the FedwireLocal key/value pairs, retrieved from the query payloads in steps two and four.

1. key: legalType; value: PRIVATE or BUSINESS
2. key: abartn; value: Fedwire routing number, 9 characters
3. key: accountNumber; value: recipient's account number
4. key: accountType; value: CHECKING or SAVINGS
5. key: address.country; value: recipient's 2-letter country code in capital letters (US)
6. key: address.city; value: recipient's city of residence
7. key: address.firstLine; value: recipient's address
8. key: address.state; value: recipient's 2-letter state code in capital letters (NY)
9. key: address.postCode; value: recipient's zip or postal code

Keep your list of beneficiary key/value pairs ready. You'll need them to compile the next query and to initiate your transfer.

Beneficiary input example

  {...}

      internationalBeneficiary: {
        name: "Emilia Brunner"
        currency: "USD"
        details: [
          { key: "legalType", value: "PRIVATE" },
          { key: "abartn", value: "020123456" },
          { key: "accountNumber", value: "12345678" },
          { key: "accountType", value: "CHECKING" },
          { key: "address.country", value: "US" },
          { key: "address.city", value: "Utica" },
          { key: "address.firstLine", value: "1 Canoga Blvd" },
          { key: "address.state", value: "NY" },
          { key: "address.postCode", value: "13505" }
        ]
        route: FedwireLocal
      }

  {...}