Recipients

As the name suggests, recipients are a core part of Rampable — the very reason Rampable exists is so you can have secure transactions with your recipients. On this page, we'll dive into the different recipient endpoints you can use to manage recipients programmatically. We'll look at how to query, create, update, and delete recipients.

The recipient model

The recipient model contains all the information about your recipients, such as their username, avatar, and phone number. It also contains a reference to the conversation between you and the recipient and information about when they were last active on Rampable.

Properties

Name
id
Type
string
Description
Unique identifier for the recipient.
Name
name
Type
string
Description
The name for the recipient.
Name
recipientType
Type
string
Description
The type of recipient. This can be either Individual or Business.
Name
email
Type
string
Description
The recipient email address.
Name
organizationId
Type
string
Description
Unique identifier for the organization associated with the recipient.
Name
userId
Type
string
Description
Unique identifier for the user associated with the recipient.
Name
createdAt
Type
timestamp
Description
Timestamp of when the recipient was created.
Name
updatedAt
Type
timestamp
Description
Timestamp of when the recipient was last updated.
Name
bank
Type
array
Description
The bank account information for the recipient. Array object with the Bank property.
Name
city
Type
string
Description
City of the recipient.
Name
address
Type
string
Description
Address of the recipient.
Name
postCode
Type
string
Description
Post code of the recipient.
Name
reference
Type
string
Description
Reference of the recipient.

GET/v1/recipients

List all recipients

This endpoint allows you to retrieve a paginated list of all your recipients. By default, a maximum of ten recipients are shown per page.

Query Params attributes

Name
limit
Type
integer
Description
Limit the number of recipients returned.
Name
sort
Type
string
Description
Sort the recipients by a specific field. You can sort by createdAt or updatedAt. By default, recipients are sorted by createdAt. You can also sort in reverse order by adding a hyphen (-) before the field you want to sort by.
Name
search
Type
string
Description
Search for a recipient by name or email.
Name
country
Type
string
Description
Filter recipients by bank country and currency.
Name
currency
Type
string
Description
Filter recipients by bank country and currency.

Request

GET

/v1/recipient

curl -G "https://sandbox.rampable.co/v1/recipient?search=example&limit=10&currency=INR&page=1&sort=-createdAt" \
    -H "Authorization: Bearer YOUR_TOKEN"

Response

{
    "statusCode": 200,
    "message": "getQueryRecipient executed successfully",
    "data": {
        "docs": [
            {
                "name": "XXXXXX",
                "recipientType": "Individual",
                "email": "XXXXXX@mail.com",
                "bank": [
                    {
                        "accountName": "XXXXXX",
                        "bankName": "XXXXXX XXXXXX",
                        "accountNumber": 12345678910,
                        "paymentCode": "XXXXXX",
                        "currency": "SGD",
                        "country": "SINGAPORE",
                        "achNumber": "1",
                        "fedwireNumber": "1",
                        "ibanNumber": "1",
                        "accountType": "Checking",
                        "_id": "XXXXXX"
                    }
                ],
                "organizationId": "XXXXXX",
                "userId": "XXXXXX",
                "createdAt": "2023-09-27T09:47:58.526Z",
                "updatedAt": "2023-09-27T09:47:58.526Z",
                "address": "XXXXXX",
                "city": "XXXXXX",
                "postCode": "XXXXXX",
                "reference": "XXXXXX",
                "id": "XXXXXX"
            },
            {
                "name": "XXXXXX",
                "recipientType": "Individual",
                ....
            }
        ],
        "totalDocs": 9,
        "offset": 0,
        "limit": 1,
        "totalPages": 9,
        "page": 1,
        "pagingCounter": 1,
        "hasPrevPage": false,
        "hasNextPage": true,
        "prevPage": null,
        "nextPage": 2
    }
  }

POST/v1/recipient

Create a recipient

This endpoint allows you to add a new recipient to your recipient list in Rampable. To add a recipient, you must provide their Rampable name and email also bank country and currency.

For recipient that use for disbursement, you can get bank information from the banks endpoint.

Required attributes

Name
name
Type
string
Description
The name for the recipient.
Name
email
Type
string
Description
The recipient email address.
Name
address
Type
string
Description
The address of recipient.
Name
city
Type
string
Description
The city of recipient.
Name
postCode
Type
string
Description
The post code of recipient.
Name
bank.accountName
Type
string
Description
The name of the bank account holder.
Name
bank.currency
Type
string
Description
The currency of the bank account.
Name
bank.country
Type
string
Description
The country of the bank account.

Optional attributes

Name
recipientType
Type
string
Description
The name for the recipient.
Name
organizationId
Type
string
Description
Unique identifier for the organization associated with the recipient.
Name
reference
Type
string
Description
The reference of recipient, you can fill to anything you want to, this fields is only for additional information
Name
bank.bankName
Type
string
Description
The name of the bank.
Name
bank.accountNumber
Type
string
Description
The bank account number.
Name
bank.paymentCode
Type
string
Description
The payment code for the bank account.
Name
bank.achNumber
Type
string
Description
The ACH number for the bank account.
Name
bank.fedwireNumber
Type
string
Description
The Fedwire number for the bank account.
Name
bank.ibanNumber
Type
string
Description
The IBAN number for the bank account.
Name
bank.accountType
Type
string
Description
The type of bank account. This can be either Checking or Savings.

Request

POST

/v1/recipient

curl -X POST "https://sandbox.rampable.co/v1/recipient" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_TOKEN" \
-d '{
    "name": "XXXXX",
    "recipientType": "Individual",
    "email": "XXXXX@mail.com",
    "organizationId": "XXXXX",
    "bank": {
        "currency": "USD",
        "country": "UNITED STATES",
        "accountNumber": "23123232123",
        "accountName": "XXXXX",
        "paymentCode": "XXXXX",
        "bankName": "XXXXX",
        "ifsc": "",
        "ibanNumber": "1",
        "achNumber": "1",
        "fedwireNumber": "1",
        "accountType": "Checking"
    },
    "city": "New York",
    "postCode": "1234",
    "address": "NY Street 123",
    "reference": "XXXXX"
}'

Response

{
    "statusCode": 200,
    "message": "Recipient created successfully",
    "data": {
      "name": "XXXXXX",
      "recipientType": "Individual",
      "email": "XXXXXX@mail.com",
      "bank": [
          {
              "accountName": "XXXXXX",
              "bankName": "XXXXXX XXXXXX",
              "accountNumber": 12345678910,
              "paymentCode": "XXXXXX",
              "currency": "SGD",
              "country": "SINGAPORE",
              "achNumber": "1",
              "fedwireNumber": "1",
              "ibanNumber": "1",
              "accountType": "Checking",
              "_id": "XXXXXX"
          }
      ],
      "organizationId": "XXXXXX",
      "userId": "XXXXXX",
      "createdAt": "2023-09-27T09:47:58.526Z",
      "updatedAt": "2023-09-27T09:47:58.526Z",
      "id": "XXXXXX",
      "city": "New York",
      "postCode": "1234",
      "address": "NY Street 123",
      "reference": "XXXXX"
    },
  }

PATCH/v1/recipient/:id

Update a recipient

This endpoint allows you to perform an update on a recipient. Currently, the only attribute that can be updated on recipients is the name attribute which controls how a recipient appears in your recipient list in Rampable.

Required attributes

Name
name
Type
string
Description
The name for the recipient.
Name
email
Type
string
Description
The recipient email address.
Name
address
Type
string
Description
The address of recipient. (can't be empty)
Name
city
Type
string
Description
The city of recipient. (can't be empty)
Name
postCode
Type
string
Description
The post code of recipient. (can't be empty)
Name
bank.accountName
Type
string
Description
The name of the bank account holder.

Optional attributes

Name
reference
Type
string
Description
The reference of recipient.
Name
bank.currency
Type
string
Description
The currency of the bank account.
Name
bank.country
Type
string
Description
The country of the bank account.
Name
recipientType
Type
string
Description
The name for the recipient.
Name
organizationId
Type
string
Description
Unique identifier for the organization associated with the recipient.
Name
bank.bankName
Type
string
Description
The name of the bank.
Name
bank.accountNumber
Type
string
Description
The bank account number.
Name
bank.paymentCode
Type
string
Description
The payment code for the bank account.
Name
bank.achNumber
Type
string
Description
The ACH number for the bank account.
Name
bank.fedwireNumber
Type
string
Description
The Fedwire number for the bank account.
Name
bank.ibanNumber
Type
string
Description
The IBAN number for the bank account.
Name
bank.accountType
Type
string
Description
The type of bank account. This can be either Checking or Savings.

Request

PATCH

/v1/contacts/6511281bc3bfaa8e0df5ff26

curl -X PATCH "https://sandbox.rampable.co/v1/recipient" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_TOKEN" \
-d '{
    "name": "XXXXX",
    "bank": {
        "currency": "USD"
    }
}'

Response

{
    "statusCode": 200,
    "message": "Recipient updated successfully",
    "data": {
      "name": "XXXXXX",
      "recipientType": "Individual",
      "email": "XXXXXX@mail.com",
      "bank": [
          {
              "accountName": "XXXXXX",
              "bankName": "XXXXXX XXXXXX",
              "accountNumber": 12345678910,
              "paymentCode": "XXXXXX",
              "currency": "SGD",
              "country": "SINGAPORE",
              "achNumber": "1",
              "fedwireNumber": "1",
              "ibanNumber": "1",
              "accountType": "Checking",
              "_id": "XXXXXX"
          }
      ],
      "organizationId": "XXXXXX",
      "userId": "XXXXXX",
      "createdAt": "2023-09-27T09:47:58.526Z",
      "updatedAt": "2023-09-27T09:47:58.526Z",
      "city": "New York",
      "postCode": "1234",
      "address": "NY Street 123",
      "reference": "XXXXX"
      "id": "XXXXXX"
    },
}

DELETE/v1/recipient/:id

Delete a recipient

This endpoint allows you to delete recipient from your recipient list in Rampable.

Request

DELETE

/v1/recipient/651602581033ce187867a766

curl -X DELETE "https://sandbox.rampable.co/v1/recipient?id=651602581033ce187867a766"

Response

{
    "statusCode": 200,
    "message": "Recipient deleted successfully",
    "data": {
      "name": "XXXXXX",
      "recipientType": "Individual",
      "email": "XXXXXX@mail.com",
      "bank": [
          {
              "accountName": "XXXXXX",
              "bankName": "XXXXXX XXXXXX",
              "accountNumber": 12345678910,
              "paymentCode": "XXXXXX",
              "currency": "SGD",
              "country": "SINGAPORE",
              "achNumber": "1",
              "fedwireNumber": "1",
              "ibanNumber": "1",
              "accountType": "Checking",
              "_id": "XXXXXX"
          }
      ],
      "organizationId": "XXXXXX",
      "userId": "XXXXXX",
      "createdAt": "2023-09-27T09:47:58.526Z",
      "updatedAt": "2023-09-27T09:47:58.526Z",
      "city": "New York",
      "postCode": "1234",
      "address": "NY Street 123",
      "reference": "XXXXX"
      "id": "XXXXXX"
    },
}