1M1money
crate::web::openapi::recipients

POST /v1/customers/{customer_id}/recipients

Changed on

Request

Path parameters

customer_idstring required

Unique identifier of the customer

Headers

Idempotency-Keystring required

UUID v4 for idempotent requests

Request body

business_type'INDIVIDUAL' | 'COMPANY' required
first_namestring nullable

First name (required for INDIVIDUAL)

last_namestring nullable

Last name (required for INDIVIDUAL)

company_namestring nullable

Company name (required for COMPANY)

nicknamestring nullable

Display name for the recipient

emailstring nullable

Email address

mobile_codestring nullable

Mobile country code (e.g., +1)

mobile_numstring nullable

Mobile number

relationship'EMPLOYEE' | 'CONTRACTOR' | 'VENDOR' | 'SUBSIDIARY' | 'MERCHANT' | 'CUSTOMER' | 'LANDLORD' | 'FAMILY' | 'OTHER' | 'NotSet' required

Example request

{
  "first_name": "John",
  "last_name": "Doe",
  "company_name": "ABC Company Ltd",
  "nickname": "John's Business Account",
  "email": "test@test.com",
  "mobile_code": "+1",
  "mobile_num": "2125551234",
  "address": {
    "address_line1": "490 2nd St",
    "address_line2": "Suite 300",
    "city": "San Francisco",
    "region": "CA",
    "postal_code": "94107"
  },
  "bank_accounts": [
    {
      "network": "SWIFT",
      "nickname": "Primary Operating Account",
      "account_holder_name": "TechStart Holdings LLC",
      "currency": "USD",
      "account_number": "4447891623",
      "institution_clearing_code": "021000021",
      "intermediary_bank": {
        "institution_id": "PNBPUS3NNYC"
      }
    }
  ]
}

Response

Recipient created successfully

recipient_idstring required

Counterparty ID. Empty values are still allowed for legacy DB columns where an empty cpid means the record is not tied to a recipient.

customer_idstring required

Portfolio ID — also exposed as customer_id in OpenAPI. Identifies one individual application / portfolio row within an entity.

business_typestring required

Recipient type: INDIVIDUAL or COMPANY

full_namestring required

Full name computed from name fields

nicknamestring nullable

User-defined nickname (optional)

emailstring nullable

Email address (optional)

relationshipstring nullable

Relationship to the customer (optional)

statusstring required

Recipient status. Possible values: success, pending_review, blocked

created_atstring date-time required

Created timestamp

modified_atstring date-time required

Last modified timestamp

Example response

{
  "recipient_id": "4728c2b9-6df7-11f0-b1f6-6a7838eca3f8",
  "customer_id": "14f20ebd-893b-11f0-b308-2eaa4f6974f2",
  "business_type": "INDIVIDUAL",
  "full_name": "John Doe",
  "nickname": "John's Business",
  "email": "john.doe@example.com",
  "relationship": "VENDOR",
  "status": "success",
  "address": {
    "full_address": "490 2nd St Suite 300, San Francisco, CA 94107",
    "country_code": "USA",
    "address_line1": "490 2nd St",
    "address_line2": "Suite 300",
    "city": "San Francisco",
    "region": "CA",
    "postal_code": "94107"
  },
  "action_required": {
    "type": "RFI",
    "case_id": "TC-WXYZ-2345",
    "action": "SUBMIT_INFORMATION"
  },
  "created_at": "2025-10-29T02:46:25.096305Z",
  "modified_at": "2025-10-29T02:46:25.096305Z",
  "bank_accounts": [
    {
      "external_account_id": "381b013e-8893-11f0-b308-2eaa4f6974f2",
      "customer_id": "14f20ebd-893b-11f0-b308-2eaa4f6974f2",
      "failure_reason": "Intermediary bank required. Confirm the details and re-add this account.",
      "network": "ETHEREUM",
      "nickname": "Primary Operating Account",
      "account_holder_name": "TechStart Holdings LLC",
      "currency": "USDC",
      "account_number": "4447891623",
      "institution_id": "CHASUS33",
      "institution_name": "JPMorgan Chase Bank, N.A.",
      "institution_clearing_code": "021000021",
      "intermediary_bank": {
        "institution_id": "PNBPUS3NNYC"
      },
      "reference_code": "36AC1ECAF659",
      "created_at": "2025-08-21T07:56:57.981Z",
      "modified_at": "2025-08-21T07:56:57.981Z",
      "recipient": {
        "recipient_id": "4728c2b9-6df7-11f0-b1f6-6a7838eca3f8",
        "customer_id": "14f20ebd-893b-11f0-b308-2eaa4f6974f2",
        "business_type": "INDIVIDUAL",
        "full_name": "John Doe",
        "nickname": "John's Business",
        "email": "john.doe@example.com",
        "relationship": "VENDOR",
        "status": "success",
        "address": {
          "full_address": "490 2nd St Suite 300, San Francisco, CA 94107",
          "country_code": "USA",
          "address_line1": "490 2nd St",
          "address_line2": "Suite 300",
          "city": "San Francisco",
          "region": "CA",
          "postal_code": "94107"
        },
        "action_required": {
          "type": "RFI",
          "case_id": "TC-WXYZ-2345",
          "action": "SUBMIT_INFORMATION"
        },
        "created_at": "2025-10-29T02:46:25.096305Z",
        "modified_at": "2025-10-29T02:46:25.096305Z"
      },
      "recipient_id": "4728c2b9-6df7-11f0-b1f6-6a7838eca3f8"
    }
  ]
}

Changes

  • d213edbaccb6Revision changes
    • breaking

      removed the enum value Unknown of the request property

    • breaking

      the / request property's minLength was increased from 0 to 1

    • breaking

      the / request property's minLength was increased from 0 to 1

    • breaking

      the / request property's minLength was increased from 0 to 1

    • breaking

      the // request property's minLength was increased from 0 to 1

    • warning

      the / request property's maxLength was set to 70

    • warning

      the / request property's maxLength was set to 70

    • warning

      the / request property's maxLength was set to 64

    • warning

      the / request property's maxLength was set to 32

    • warning

      the / request property's maxLength was set to 64

    • warning

      the // request property's maxLength was set to 64

    • warning

      the // request property's maxLength was set to 32

    • warning

      the // request property's maxLength was set to 64

    • warning

      the /////// request property's maxLength was set to 64

    • warning

      the // request property's maxLength was set to 64

    • warning

      the request property's maxLength was set to 70

    • warning

      the request property's maxLength was set to 32

    • warning

      the request property's maxLength was set to 32

    • warning

      the request property's maxLength was set to 8

    • warning

      the request property's maxLength was set to 32

    • warning

      the request property's maxLength was set to 128

    • info

      api tag crate::web::openapi::recipients added

    • info

      api tag Recipients (Send to Others) removed

    • info

      added the new optional request property //

    • info

      the request property // became nullable

    • info

      the request property // became optional

    • info

      added the new BES enum value to the request property /

    • info

      added the new BES enum value to the request property //

    • info

      added the new NotSet enum value to the request property

    • info

      added subschema #1 subschema #2 to the response body allOf list for the response status

    • info

      removed subschema #1 subschema #2 from the response body allOf list for the response status