Add Contact to Wallet

Add a personal contact to a company wallet or client wallet.
This page also includes details on the required parameters for a business contact_type that should be added when creating a company wallet:
- address
- business_details
- country

Note

The status of the wallet must be ACT (enabled).
You can only add a personal contact to a company wallet or a client wallet.
For best practices, include the first_name, last_name, date_of_birth, country, address.name and address.line_1 fields. These fields are required for other operations.
To change parameter values of a wallet contact, see Update Wallet Contact.
The code samples include successful requests (200) and bad requests (400).
- For error messages that appear due to bad requests (400), see:
  - General Errors
  - Wallet Contact Errors
- For information about unauthorized request (401) and other authentication errors, see Troubleshooting Authentication and Authorization Errors.

Parameters

Request Path Parameters

- wallet
- ID of the Rapyd Wallet that this contact is associated with. String starting with ewallet_.

Request Header Parameters

Request Body Parameters

- address
- Address of this contact person. Required when the client issues a card to the contact. This can be an address object or the ID of an address object created with Create Address. Also required when creating a company wallet with a business contact-type. See samples in Create Wallet.
  canton
  Name of the canton administrative subdivision, as used in banking.
  city
  City portion of the address.
  Required for issuance of a card to the wallet contact. Required for creating a Visa card payment that requires 3DS.
  country
  The two-letter ISO 3166-1 ALPHA-2 code for the country.
  Required for creating a Visa card payment that requires 3DS.
  district
  Name of the district administrative subdivision, as used in banking.
  line_1
  Line 1 of the address, such as a building number and street name.
  Required for creating a Visa card payment that requires 3DS.
  line_2
  Line 2 of the address, such as a suite or apartment number, or the name of a named building.
  line_3
  Line 3 of the address.
  metadata
  A JSON object defined by the client. See Metadata.
  name
  The name of a contact person or an "in care of" person at this address. For a personal wallet contact type, alphabetic characters and spaces.
  Required for creating a Visa card payment that requires 3DS.
  phone_number
  Phone number associated with this specific address in E.164 format. Must be unique.
  Required for creating a Visa card payment that requires 3DS.
  state
  State or province portion of the address.
  Required for creating a Visa card payment that requires 3DS.
  zip
  Postal code portion of the address.
  Required for creating a Visa card payment that requires 3DS.
- business_details
- Describes additional information for business entities. Required when creating a company wallet with a business contact_type. See also the 'Create company wallet' samples in Create Wallet.
  address
  Principal address of the business. Values for name and line_1 are required. See Create Address.
  Note
  Payment Facilitator (PayFac) only. The following additional values are required when a PayFac creates a wallet for a sub-merchant:
  city
  country
  line_2
  phone_number
  zip
  annual_revenue
  Annual revenue of the business in US dollars. Maximum value: 100000000000000. Decimal.
  cnae_code
  Business activity code of the business, according to the Classificação Nacional de Atividades Econômicas of Brazil. Alphanumeric string. Maximum 7 characters.
  customer_service_phone_number
  Payment Facilitator (PayFac) only. Required when a PayFac creates a wallet for a sub-merchant. Phone number for contacting the customer support service of the sub-merchant business, in E.164 format.
  entity_type
  Type of business entity. One of the following:
  sole_prop - Sole proprietorship.
  partnership - Partnership.
  company - Company.
  government - Government agency.
  charity - Charity.
  NPO - Non-profit organization.
  association - Unincorporated business association.
  trust - Trust.
  establishment_date
  Date that the business was established. Format: YYYY-MM-DD.
  industry_category
  Name of the industry that this business belongs to. Alphanumeric string with no special characters.
  industry_sub_category
  Subcategory of the industry that this business belongs to.
  legal_entity_type
  Type of legal entity. Alphanumeric string.
  mcc
  Payment Facilitator (PayFac) only. Required when a PayFac creates a wallet for a sub-merchant. Four-digit merchant category code (MCC) of the sub-merchant business, as defined in ISO 18245.
  name
  Business name.
  registration_number
  Registration number.
  statement_descriptor
  Payment Facilitator (PayFac) only. Required when a PayFac creates a wallet for a sub-merchant. The sub-merchant name or business name. Maximum: 22 characters. If the maximum is exceeded, the INVALID_FIELDS error is returned. See General Errors.
  website_url
  Payment Facilitator (PayFac) only. Required when a PayFac creates a wallet for a sub-merchant. URL of the sub-merchant business website.
- contact_reference_id
- ID of a wallet contact, defined by the customer or end user. String. Must be unique and cannot start with cont_.
- country
- The two-letter ISO 3166-1 ALPHA-2 code for the country.
  To determine the code for a country, see List Countries. A wallet must contain a contact with a valid country value. Also required when creating a company wallet with a business contact-type.
- date_of_birth
- Date of birth of the individual. One of the following formats:
  - MM/DD/YYYY
  - YYYY-MM-DD
- email
- Email address of the contact.
- first_name
- First name of the personal contact or primary person associated with the business contact. For a personal contact type, alphabetic characters and spaces.
- gender
- Gender of the personal contact or primary person associated with the business contact. One of the following values:
  - male
  - female
  - other
  - not_applicable
- house_type
- Description of the type of residency at the contact's residence. One of the following values:
  - lease - A long-term lease.
  - live_with_family - The contact lives with family.
  - own - The contact owns the residence.
  - owner - The contact is the owner of the residence.
  - month_to_month - An informal agreement, renewable each month.
  - housing_project - A room in a large residence facility, such as a residence hall or senior citizens' home.
- identification_number
- ID number as shown by the ID document.
- identification_type
- Type of the identification document associated with the contact.
  For types that are valid in the country, use List Official Identification Documents.
- last_name
- Family name of the personal contact or primary person associated with the business contact. For a personal contact type, alphabetic characters and spaces.
  Required for issuing a card to a personal contact.
- marital_status
- Marital status of the personal contact or primary person associated with the business contact. One of the following values:
  - married
  - single
  - divorced
  - widowed
  - cohabiting
  - not_applicable
- metadata
- A JSON object defined by the client. See Metadata.
- middle_name
- Middle name of the personal contact or primary person associated with the business contact.
- mothers_name
- Name of the mother of the personal contact or primary person associated with the business contact. Alphabetic characters and spaces.
- nationality
- The citizenship of the contact. Two-letter ISO 3166-1 ALPHA-2 code for the country. To determine the code for a country, see List Countries.
- phone_number
- Phone number of the contact in E.164 format.
- second_last_name
- Second last name of the personal contact or primary person associated with the business contact.
- send_notifications
- Determines whether Rapyd sends notifications to the contact. Default is false.

Response Parameters

- address
- Address of this contact person. Required when the client issues a card to the contact. This can be an 'address' object or the ID of an address object. For more information about the fields of the 'address' object, see Create Address.
- business_details
- Describes additional information for business entities. Required when type is company.
  address
  Principal address of the business. See Create Address.
  annual_revenue
  Annual revenue of the business in US dollars. Maximum value: 100000000000000. Decimal.
  cnae_code
  Business activity code of the business, according to the Classificação Nacional de Atividades Econômicas of Brazil. Alphanumeric string. Maximum 7 characters.
  created_at
  Time of creation of the business_details object, in Unix time.
  customer_service_phone_number
  Phone number for contacting the customer support service of the sub-merchant business, in E.164 format. Relevant to Payment Facilitator (PayFac).
  entity_type
  Type of business entity. One of the following:
  sole_prop - Sole proprietorship.
  partnership - Partnership.
  company - Company.
  government - Government agency.
  charity - Charity.
  NPO - Non-profit organization.
  association - Unincorporated business association.
  trust - Trust.
  establishment_date
  Date that the business was established. Format: YYYY-MM-DD.
  id
  ID of the business_details object. String starting with busi_.
  industry_category
  Name of the industry that this business belongs to. Alphanumeric string with no special characters.
  industry_sub_category
  Subcategory of the industry that this business belongs to.
  legal_entity_type
  Type of legal entity. Alphanumeric string.
  mcc
  Four-digit merchant category code (MCC) of the sub-merchant business, as defined in ISO 18245. Relevant to Payment Facilitator (PayFac).
  name
  Business name.
  registration_number
  Registration number.
  statement_descriptor
  The sub-merchant name or business name.. Relevant to Payment Facilitator (PayFac).
  website_url
  URL of the sub-merchant business website. Relevant to Payment Facilitator (PayFac).
- compliance_profile
- Indicates the degree to which this contact can use the wallet. One of the following:
  - 1 - All transactions are allowed.
  - 0 - The wallet is limited, and the contact must complete the identity verification process.
  - -1 - The wallet is restricted and cannot be used for any transactions.
- contact_reference_id
- ID of a wallet contact, defined by the customer or end user. Must be unique. String. Cannot start with cont_.
- contact_type
- Type of contact. One of the following:
  - personal - An individual customer.
  - business - A business customer.
- country
- The two-letter ISO 3166-1 ALPHA-2 code for the country.
  To determine the code for a country, see List Countries.
- created_at
- Time of creation of the contact object, in Unix time.
- date_of_birth
- Date of birth of the individual. Format: YYYY-MM-DD
- email
- Email address of the contact.
- ewallet
- ID of the Rapyd Wallet that this contact is associated with. String starting with ewallet_.
- first_name
- First name of the personal contact or primary person associated with the business contact. For a personal contact type, alphabetic characters and spaces.
- gender
- Gender of the personal contact or primary person associated with the business contact. One of the following values:
  - male
  - female
  - other
  - not_applicable
- house_type
- Description of the type of residency at the contact's residence. One of the following values:
  - lease - A long-term lease.
  - live_with_family - The contact lives with family.
  - own - The contact owns the residence.
  - owner - The contact is the owner of the residence.
  - month_to_month - An informal agreement, renewable each month.
  - housing_project - A room in a large residence facility, such as a residence hall or senior citizens' home.
- id
- ID of the contact object. String starting with cont_.
- identification_number
- ID number as shown by the ID document.
- identification_type
- Type of the identification document associated with the contact.
  For types that are valid in the country, use List Official Identification Documents.
- issued_card_data
- Describes additional information about the business contact for a company wallet.
  preferred_name
  The name of the contact person.
  transaction_permissions
  Indicates permissions for issuing transactions. Possible values:
  allowed
  not_allowed
  role_in_company
  The role of the named person. One of the following values:
  owner - Sole proprietor or partner.
  agent - Authorized agent or attorney in fact.
  employee - Authorized employee.
- last_name
- Family name of the personal contact or primary person associated with the business contact. For a personal contact type, alphabetic characters and spaces. Required for issuing a card to a personal contact.
- marital_status
- Marital status of the personal contact or primary person associated with the business contact. One of the following values:
  - married
  - single
  - divorced
  - widowed
  - cohabiting
  - not_applicable
- metadata
- A JSON object defined by the client. See Metadata.
- middle_name
- Middle name of the personal contact or primary person associated with the business contact.
- mothers_name
- Name of the mother of the personal contact or primary person associated with the business contact. Alphabetic characters and spaces.
- nationality
- The citizenship of the contact. Two-letter ISO 3166-1 ALPHA-2 code for the country. To determine the code for a country, see List Countries.
- phone_number
- Phone number of the contact in E.164 format.
- second_last_name
- Second last name of the personal contact or primary person associated with the business contact.
- send_notifications
- Determines whether Rapyd sends notifications to the contact. Default is false.
- verification_status
- Result of the verification check. One of the following:
  - not verified - The contact has not been submitted for the Know Your Customer checks.
  - KYCd - The user has passed the Know Your Customer checks.

/v1/ewallets/:wallet/contacts

Add Contact to Wallet

curl -X post 'https://sandboxapi.rapyd.net/v1/ewallets/ewallet_b5320c566cc4aa01fe77440ad08693f7/contacts' \
-H 'access_key: your-access-key-here' \
-H 'Content-Type: application/json' \
-H 'idempotency: your-idempotency-parameter-here' \
-H 'salt: your-random-string-here' \
-H 'signature: your-calculated-signature-here' \
-H 'timestamp: your-unix-timestamp-here'
--data-raw '{
    "first_name": "Jane",
    "last_name": "Doe",
    "contact_type": "personal",
    "identification_type": "PA",
    "identification_number": "1233242424",
    "country": "US",
    "address": {
        "name": "Jane Doe",
        "line_1": "123 First Street",
        "city": "Anytown",
        "zip": "12345",
        "phone_number": "+14155551234"
    }
}'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "4f3ca7e4-759d-4630-aa57-1c9c4bb251ba"
    },
    "data": {
        "id": "cont_6493a93a65b59e7aa3c9c223be7cdeb4",
        "first_name": "Jane",
        "last_name": "Doe",
        "middle_name": "",
        "second_last_name": "",
        "gender": "not_applicable",
        "marital_status": "not_applicable",
        "house_type": "",
        "contact_type": "personal",
        "phone_number": "",
        "email": "",
        "identification_type": "PA",
        "identification_number": "1233242424",
        "issued_card_data": {
            "preferred_name": "",
            "transaction_permissions": "",
            "role_in_company": ""
        },
        "date_of_birth": null,
        "country": "US",
        "nationality": null,
        "address": {
            "id": "address_c5696fba97628d9f079f844bd14631b2",
            "name": "Jane Doe",
            "line_1": "123 First Street",
            "line_2": "",
            "line_3": "",
            "city": "Anytown",
            "state": "",
            "country": "",
            "zip": "12345",
            "phone_number": "+14155551234",
            "metadata": {},
            "canton": "",
            "district": "",
            "created_at": 1762174004
        },
        "ewallet": "ewallet_b5320c566cc4aa01fe77440ad08693f7",
        "created_at": 1762174004,
        "metadata": {},
        "business_details": null,
        "compliance_profile": 0,
        "verification_status": "not verified",
        "send_notifications": false,
        "mothers_name": "",
        "contact_reference_id": null
    }
}

Bad Request - Wallet Not Found

curl -X post 'https://sandboxapi.rapyd.net/v1/ewallets/ewallet_b5320c566cc4aa01fe77440ad08693f7/contacts' \
-H 'access_key: your-access-key-here' \
-H 'Content-Type: application/json' \
-H 'idempotency: your-idempotency-parameter-here' \
-H 'salt: your-random-string-here' \
-H 'signature: your-calculated-signature-here' \
-H 'timestamp: your-unix-timestamp-here'
--data-raw '{
    "first_name": "Jane",
    "last_name": "Doe",
    "contact_type": "personal",
    "identification_type": "PA",
    "identification_number": "1233242424",
    "country": "US",
    "address": {
        "name": "Jane Doe",
        "line_1": "123 First Street",
        "city": "Anytown",
        "zip": "12345",
        "phone_number": "+14155551234"
    }
}'

{
    "status": {
        "error_code": "ERROR_GET_USER",
        "status": "ERROR",
        "message": "The request attempted an operation that requires a wallet, but the wallet was not found. The request was rejected. Corrective action: Use the ID of a valid wallet that has not been deleted. The ID is a string starting with 'ewallet_'.",
        "response_code": "ERROR_GET_USER",
        "operation_id": "2f17e6d3-50c6-46c5-9af2-7dd7c95a507d"
    }
}

Bad Request - Too Many Contacts (Person Wallet)

curl -X post 'https://sandboxapi.rapyd.net/v1/ewallets/ewallet_d496b5377c6c6c1d8c0c9ba3fec1d073/contacts' \
-H 'access_key: your-access-key-here' \
-H 'Content-Type: application/json' \
-H 'idempotency: your-idempotency-parameter-here' \
-H 'salt: your-random-string-here' \
-H 'signature: your-calculated-signature-here' \
-H 'timestamp: your-unix-timestamp-here'
--data-raw '{
    "first_name": "Jane",
    "last_name": "Doe",
    "contact_type": "personal",
    "identification_type": "PA",
    "identification_number": "1233242424",
    "country": "US",
    "address": {
        "name": "Jane Doe",
        "line_1": "123 Lake Forest Drive",
        "city": "Anytown",
        "zip": "12345",
        "phone_number": "+14155551234"
    }
}'

{
    "status": {
        "error_code": "ERROR_ADD_CONTACT_TOO_MANY_CONTACTS",
        "status": "ERROR",
        "message": "The request tried to add a contact to a personal wallet, but a personal wallet can have only one contact. The request was rejected. Corrective action: None. Determine why an attempt was made to give a personal wallet two contacts. Consider creating a company wallet.",
        "response_code": "ERROR_ADD_CONTACT_TOO_MANY_CONTACTS",
        "operation_id": "0cce690c-8275-4944-a21b-9e6951e52694"
    }
}

In this section:

Documentation

Add Contact to Wallet

Note

Parameters

Request Path Parameters

Request Header Parameters

Request Body Parameters

Note

Response Parameters

Search results