# List beneficiaries

List registered beneficiaries with query filtering options.


# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Banking - Bank accounts",
    "version": "1.0.0",
    "description": "API for managing bank accounts in global formats",
    "contact": {
      "name": "API Support",
      "url": "https://developers.pismo.io/support/"
    },
    "license": {
      "name": "Copyright Pismo"
    }
  },
  "servers": [
    {
      "url": "https://sandbox.pismolabs.io/intl-bankaccounts",
      "description": "Sandbox API server for testing"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Beneficiaries",
      "description": "Beneficiaries management endpoints"
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Account token - token encoded with Pismo account ID. Tokens can expire quickly, which can result in an **401 Unauthorized** error.",
        "bearerFormat": "JWT"
      }
    },
    "parameters": {
      "auth": {
        "name": "AuthorizationHeader",
        "in": "header",
        "description": "Account token - Token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a **401 Unauthorized** error. \n",
        "required": true,
        "schema": {
          "type": "string"
        },
        "example": 1234
      }
    },
    "schemas": {
      "accountID": {
        "type": "integer",
        "description": "Account ID",
        "example": 78123456
      },
      "brazilAccountType": {
        "type": "string",
        "enum": [
          "CACC",
          "SLRY",
          "SVGS",
          "TRAN"
        ],
        "maxLength": 4,
        "description": "Account type:  \n  `CACC` - Checking/current account. Known as \"conta corrente\" in Portuguese, this is a bank account type designed for everyday financial transactions and is the most common type individuals and businesses use for day-to-day banking.\n  `SVGS` - Savings account\n  `TRAN` - Payment account. Payment institutions offer payment accounts to move funds and make payments, while banks offer checking accounts that include full financial services such as credit and investments.\n  `SLRY` - Salary account. Employer deposits a fixed amount every month.\n",
        "example": "TRAN"
      },
      "beneBankCode": {
        "type": "string",
        "description": "Beneficiary bank code.",
        "maxLength": 20,
        "example": "1086"
      },
      "beneBranch": {
        "maxLength": 50,
        "description": "Beneficiary branch.",
        "type": "string",
        "example": "5555555"
      },
      "beneAccountCode": {
        "type": "string",
        "maxLength": 50,
        "description": "Beneficiary account code.",
        "example": "7654321"
      },
      "beneAlias": {
        "type": "string",
        "maxLength": 20,
        "description": "Beneficiary alias.",
        "example": "Curveball"
      },
      "beneName": {
        "type": "string",
        "description": "Beneficiary's first and last name.",
        "maxLength": 50,
        "example": "Al Freydough"
      },
      "beneDocNumber": {
        "type": "string",
        "description": "A government document number, such as a Social Security number (US) or Cadastro de Pessoas Físicas number (Brazil). \n",
        "maxLength": 20,
        "example": "123412341234"
      },
      "beneID": {
        "type": "string",
        "maxLength": 32,
        "description": "UUID identifying beneficiary.",
        "example": "123e4567-e89b-12d3-a456-42661417"
      },
      "beneEnabled": {
        "type": "boolean",
        "description": "Is beneficiary active flag.",
        "example": true
      },
      "beneficiaries.Beneficiary": {
        "type": "object",
        "properties": {
          "account_code": {
            "$ref": "#/components/schemas/beneAccountCode"
          },
          "account_id": {
            "$ref": "#/components/schemas/accountID"
          },
          "account_type": {
            "$ref": "#/components/schemas/brazilAccountType"
          },
          "alias": {
            "$ref": "#/components/schemas/beneAlias"
          },
          "bank_code": {
            "$ref": "#/components/schemas/beneBankCode"
          },
          "beneficiary_id": {
            "$ref": "#/components/schemas/beneID"
          },
          "branch": {
            "$ref": "#/components/schemas/beneBranch"
          },
          "creation_datetime": {
            "$ref": "#/components/schemas/creationDatetime"
          },
          "document_number": {
            "$ref": "#/components/schemas/beneDocNumber"
          },
          "enabled": {
            "$ref": "#/components/schemas/beneEnabled"
          },
          "name": {
            "$ref": "#/components/schemas/beneName"
          },
          "region": {
            "$ref": "#/components/schemas/regionCode"
          },
          "schema": {
            "$ref": "#/components/schemas/beneSchema"
          },
          "updated_datetime": {
            "$ref": "#/components/schemas/updatedDatetime"
          }
        }
      },
      "beneficiaries.SearchBeneficiaryResponse": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/beneficiaries.Beneficiary"
            }
          },
          "last_evaluated_creation_datetime": {
            "type": "string",
            "description": "Use this field to get next results"
          },
          "per_page": {
            "type": "integer",
            "description": "Items per page.",
            "example": 10
          },
          "total_items": {
            "type": "integer",
            "description": "Total items",
            "example": 100
          }
        }
      },
      "beneSchema": {
        "type": "string",
        "description": "Beneficiary schema validation: \n\n  `BANKACCOUNT` -  `account_code` contains a Brazilian account number (used in junction with the `bank_code` and `branch` fields)\n\n  `PIX` - `account_code` contains a valid Pix key. For more information, see <a href=\"https://developers.pismo.io/pismo-docs/docs/pix-instant-payments\" target=\"_blank\">Pix instant payments</a>\n\n `DOCUMENTNUMBER` - `account_code` contains a valid Brazilian document number. This is government document number, such as Cadastro de Pessoas Físicas number - a Brazilian tax registry number, similar to a Social Security number in the US. \n",
        "enum": [
          "BANKACCOUNT",
          "PIX",
          "DOCUMENTNUMBER"
        ],
        "example": "PIX"
      },
      "creationDatetime": {
        "type": "string",
        "format": "date-time",
        "description": "Account creation date time displayed in ISO 8601 format `2023-04-12T23:20:50.52Z`.",
        "example": "2023-04-12T23:20:50.52Z"
      },
      "domain.Error": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Error type code",
            "example": "EIBA0001"
          },
          "details": {
            "type": "string",
            "description": "Error details",
            "example": "Key not found"
          },
          "message": {
            "type": "string",
            "description": "Error message",
            "example": "Key not found"
          }
        }
      },
      "regionCode": {
        "type": "string",
        "description": "ISO-3166 two letter country code. For example, BR=Brazil.",
        "example": "BR"
      },
      "updatedDatetime": {
        "type": "string",
        "format": "date-time",
        "description": "Updated date time. A RFC 3339 value, i.e., \"2023-04-12T23:20:50.52Z\".",
        "example": "2023-04-12T23:20:50.52Z"
      }
    }
  },
  "paths": {
    "/v1/beneficiaries": {
      "get": {
        "tags": [
          "Beneficiaries"
        ],
        "summary": "List beneficiaries",
        "description": "List registered beneficiaries with query filtering options.\n",
        "operationId": "get-intl-bank-accounts-v1-bank-accounts-beneficiaries",
        "parameters": [
          {
            "$ref": "#/components/parameters/auth"
          },
          {
            "name": "lastEvaluatedCreationDatetime",
            "in": "query",
            "description": "This is the `last_evaluated_creation_datetime` field from the response. You can use it to get the next page of results on a subsequent call.\n",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "perPage",
            "in": "query",
            "description": "Number of items per page, min=1, max=100, default=20.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "order",
            "in": "query",
            "description": "Sort order. Results are ordered on the `created_datetime` field. Default=`DESC`.",
            "schema": {
              "type": "string",
              "enum": [
                "DESC",
                "ASC"
              ]
            }
          },
          {
            "name": "name",
            "in": "query",
            "description": "Beneficiary name",
            "schema": {
              "type": "string",
              "maxLength": 50
            }
          },
          {
            "name": "alias",
            "in": "query",
            "description": "Beneficiary alias",
            "schema": {
              "type": "string",
              "maxLength": 20
            }
          },
          {
            "name": "enabled",
            "in": "query",
            "description": "Return only active or non-active beneficiaries flag. If not passed, all beneficiares are returned.",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Response Body",
            "headers": {
              "x-cid": {
                "description": "Request tracking identifier.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/beneficiaries.SearchBeneficiaryResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "headers": {
              "x-cid": {
                "description": "Request tracking identifier.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/domain.Error"
                },
                "examples": {
                  "EIBA0012": {
                    "summary": "Accounts API invalid request",
                    "value": {
                      "code": "EIBA0012",
                      "message": "Accounts - API returned 4xx error"
                    }
                  },
                  "EIBA0018": {
                    "summary": "Invalid perPage Query Parameter",
                    "value": {
                      "code": "EIBA0018",
                      "message": "Invalid value for query param 'perPage'"
                    }
                  },
                  "EIBA0019": {
                    "summary": "Invalid Datetime Query Parameter",
                    "value": {
                      "code": "EIBA0019",
                      "message": "Invalid value for datetime query parameter. RFC3339 format must be used"
                    }
                  },
                  "EIBA0020": {
                    "summary": "Invalid Boolean Query Parameter",
                    "value": {
                      "code": "EIBA0020",
                      "message": "Invalid value for boolean query parameter"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "headers": {
              "x-cid": {
                "description": "Request tracking identifier.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/domain.Error"
                },
                "examples": {
                  "EIBA0006": {
                    "summary": "Missing tenant header",
                    "value": {
                      "code": "EIBA0006",
                      "message": "Missing required header: 'x-tenant'"
                    }
                  },
                  "EIBA0007": {
                    "summary": "Invalid account ID header",
                    "value": {
                      "code": "EIBA0007",
                      "message": "Invalid account ID header: 'x-account-id'"
                    }
                  },
                  "EIBA0023": {
                    "summary": "Account status not NORMAL",
                    "value": {
                      "code": "EIBA0023",
                      "message": "Account status not NORMAL"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "headers": {
              "x-cid": {
                "description": "Request tracking identifier.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/domain.Error"
                },
                "examples": {
                  "EIBA0010": {
                    "summary": "Account not found",
                    "value": {
                      "code": "EIBA0010",
                      "message": "Account not found"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "headers": {
              "x-cid": {
                "description": "Request tracking identifier.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/domain.Error"
                },
                "examples": {
                  "EIBA0005": {
                    "summary": "HTTP error",
                    "value": {
                      "code": "EIBA0005",
                      "message": "HTTP error"
                    }
                  },
                  "EIBA0011": {
                    "summary": "Accounts API server error",
                    "value": {
                      "code": "EIBA0011",
                      "message": "Accounts - API returned 5xx error"
                    }
                  },
                  "EIBA0013": {
                    "summary": "Accounts API timeout",
                    "value": {
                      "code": "EIBA0013",
                      "message": "Accounts - API timeout"
                    }
                  },
                  "EIBA0015": {
                    "summary": "Database error",
                    "value": {
                      "code": "EIBA0015",
                      "message": "Database internal error"
                    }
                  }
                }
              }
            }
          }
        },
        "x-codegen-request-body-name": "RequestBody"
      }
    }
  }
}
```