--- updatedAt: 2026-07-09T19:39:10.000Z agentTools: projectIndex: https://developer.i-payout.com/llms.txt --- # Create beneficiary This API will create a new beneficiary. Once the account has been created, system will send an email with the credentials to the beneficiary. # OpenAPI definition ```json { "openapi": "3.0.1", "info": { "title": "IPS Portal Rest API - V1", "description": "i-payout API", "contact": { "name": "i-payout tech support", "email": "techsupport@i-payout.com" }, "license": { "name": "i-payout API", "url": "http://www.i-payout.com" }, "version": "v1" }, "paths": { "/api/v1/beneficiaries/create-spl-case": { "post": { "tags": [ "Beneficiary" ], "summary": "Create beneficiary", "description": "This API will create a new beneficiary. Once the account has been created, system will send an email with the credentials to the beneficiary.", "operationId": "create-beneficiary-spl", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterUserViewModel" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseCreateNewBeneficiary" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseCreateNewBeneficiary" } } } }, "500": { "description": "Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "security": [ { "Bearer": [], "X-MerchantId": [] } ] } } }, "components": { "schemas": { "ApiResponse": { "type": "object", "properties": { "isSuccess": { "type": "boolean", "description": "Indicates if the API call was successful or not." }, "message": { "type": "string", "description": "A human readable status message that may be used for debugging.", "nullable": true }, "statusCode": { "$ref": "#/components/schemas/StatusConstants" }, "logIdentifier": { "type": "string", "description": "Utilized for support, a log identifier to provide to i-payout when requesting technical support.", "nullable": true } }, "additionalProperties": false, "description": "Standard API Response object." }, "ApiResponseCreateNewBeneficiary": { "type": "object", "properties": { "isSuccess": { "type": "boolean", "description": "Indicates if the API call was successful or not." }, "message": { "type": "string", "description": "A human readable status message that may be used for debugging.", "nullable": true }, "statusCode": { "$ref": "#/components/schemas/StatusConstants" }, "logIdentifier": { "type": "string", "description": "Utilized for support, a log identifier to provide to i-payout when requesting technical support.", "nullable": true }, "data": { "$ref": "#/components/schemas/ApiResponseCreateNewBeneficiaryData" } }, "additionalProperties": false, "description": "Create new Beneficiary response" }, "ApiResponseCreateNewBeneficiaryData": { "type": "object", "properties": { "beneficiaryToken": { "type": "string", "description": "i-payout assigned user identifier for the account", "nullable": true } }, "additionalProperties": false, "description": "Create new Beneficiary response data." }, "RegisterUserViewModel": { "required": [ "emailAddress", "firstName", "lastName", "username" ], "type": "object", "properties": { "username": { "maxLength": 300, "type": "string", "description": "The unique username for the new customer." }, "firstName": { "maxLength": 50, "type": "string", "description": "The first name of the beneficiary." }, "lastName": { "maxLength": 50, "type": "string", "description": "The last name of the beneficiary." }, "companyName": { "maxLength": 150, "type": "string", "description": "The company name associated with the beneficiary.", "nullable": true }, "address1": { "maxLength": 250, "type": "string", "description": "The primary address of the beneficiary.", "nullable": true }, "address2": { "maxLength": 250, "type": "string", "description": "The secondary address of the beneficiary.", "nullable": true }, "city": { "maxLength": 150, "type": "string", "description": "The city where the beneficiary resides.", "nullable": true }, "state": { "maxLength": 150, "type": "string", "description": "The customer's state. For US users state should be in 2 character format like FL, TX.", "nullable": true }, "zipCode": { "maxLength": 25, "type": "string", "description": "The customer's ZIP or postal code. For US users ZIP code should be in numeric format.", "nullable": true }, "country": { "maxLength": 2, "type": "string", "description": "The customer's two-letter country code (ISO 3166-1 alpha-2). If not specified, default country is US.", "nullable": true }, "phoneNumber": { "maxLength": 50, "type": "string", "description": "The phone number of the beneficiary.", "nullable": true }, "cellPhoneNumber": { "maxLength": 50, "type": "string", "description": "The beneficiary's mobile phone number. This number can be used for SMS notifications.", "nullable": true }, "emailAddress": { "maxLength": 300, "type": "string", "description": "The email address of the beneficiary." }, "dateOfBirth": { "type": "string", "description": "The beneficiary's date of birth. It will be asked on a first user login. Format: \"yyyy-mm-dd\"", "nullable": true }, "preferredLanguage": { "maxLength": 2, "type": "string", "description": "The beneficiary's preferred language code that will be used for email communications. If not specified, it will be EN. Example: EN - English, ES - Spanish etc.\r\nAvailabel languages are: EN, ES, PT, FR, SK, ZH, DE, IT, HU, RU, PL, KO, JA, HI, ID, zh-CHT, NL, NB, SV, CS, DA", "nullable": true }, "kyc": { "type": "array", "items": { "$ref": "#/components/schemas/RegisterUserViewModelKyc" }, "nullable": true } }, "additionalProperties": false, "description": "Request model for creating new user" }, "RegisterUserViewModelKyc": { "type": "object", "properties": { "idType": { "maxLength": 50, "type": "string", "description": "Identity type of the beneficiary. Provide string value. SSN, CompanyTaxID, Passport, GovernmentID, DriversLicense, SocialInsuranceNumber, CURP, RFC, ABN, SIREN", "nullable": true }, "idNumber": { "maxLength": 50, "type": "string", "description": "Identity number of the beneficiary.", "nullable": true } }, "additionalProperties": false }, "StatusConstants": { "enum": [ "NO_ERROR", "EMAIL_ADDRESS_EXISTS", "CAPTCHA_FAILED", "INVALID_REFERENCEID", "INVALID_OPERATION", "INVALID_TIN_VALIDATION_STATUS", "RECORD_NOT_FOUND", "Already_Exist", "Batch_Closed", "IP_BLACKLISTED", "CREDIT_CARD_PROCESSOR_ISSUE", "FEES_NOT_ACCEPTED", "PAYOUT_CAPABILITIES_DISABLED", "INVALID_RECURRING_PAYMENT_STATUS", "INVOICE_CAPABILITIES_DISABLED", "INVALID_EWALLET_REGISTRATION", "PRIVATE_KEY_ISSUE", "FILE_NOT_EXISTS", "OLDUSER_NEWUSER_MISMATCH", "USER_CANNOT_CREATED", "CANNOT_CREATE_NEW_BATCH", "REFERENCEID_ALREADY_EXISTS", "DELETE_RECORD_ERROR", "FX_ConversionRate_Issue", "RATE_LIMIT_EXCEEDED", "IP_NOT_ALLOWED", "COUNTRY_NOT_ALLOWED", "INVALID_FIELD_VALUE_LENGTH", "UNAUTHORIZED_API_CALL", "FEE_VALUE_NOT_FOUND_FOR_CUSTOMER", "IPADDRESS_GENERATION_ISSUE", "MERCHANT_NOT_FOUND", "INVALID_PARAMS", "Missing_HEADER_PARAMS", "INVALID_URL", "INVALID_AMOUNT", "INVALID_CURRENCY", "REQUIRED_PARAMETER", "INVALID_REQUEST_PARAM", "INVALID_REQUEST_RESPONSE_PARAM", "INVALID_SERVER_CONFIG", "ACCESS_DENIED", "INVALID_COUNTRY_CODE", "PROCESSING", "PENDING", "NO_RECORDS_FOUND", "INVALID_MERCHANT", "PAL_INVALID_EMAIL", "INVALID_CARD_NUMBER", "INSUFFICIENT_FUNDS", "USERNAME_EXISTS", "USER_NOT_LOGGED_IN", "INVALID_CLIENT_CREDENTIALS", "ACCOUNT_NOT_FOUND", "GENERAL_ERROR", "CUSTOMER_NOT_FOUND", "INTERNAL_ERROR" ], "type": "string", "description": "Api response status code. For possible values, see Status Code Values ." } }, "securitySchemes": { "basic": { "type": "http", "description": "Use API username and password to get the dynamic bearer token which can be used to access all other API, Example: 'Basic 12345adfad'", "scheme": "basic" }, "Bearer": { "type": "apiKey", "description": "JWT Authorization header using the Bearer scheme.Enter 'Bearer' [space] and then your token in the text input below. Example: 'Bearer 12345abcdef'", "name": "Authorization", "in": "header" }, "X-MerchantId": { "type": "apiKey", "description": "Merchant Identifier (GUID)", "name": "X-MerchantId", "in": "header" } } }, "security": [ { "Bearer": [], "basic": [], "X-MerchantId": [] } ] } ```