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

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.
You can only add a personal contact to a company wallet or a client wallet.
To change parameter values of a wallet contact, see Update Wallet Contact.
The code samples include successful requests (200), bad requests (400), and an unauthorized request (401). For all error messages that appear due to bad requests, see Wallet Contact Errors, Wallet Errors, and General 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

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"
    }
}

Unauthorized

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": "UNAUTHENTICATED_API_CALL",
        "status": "ERROR",
        "message": "The request was rejected due to an authentication issue. Corrective action: Check the status of your account in the 'Account Details' page of the Client Portal.",
        "response_code": "UNAUTHENTICATED_API_CALL",
        "operation_id": "23747610-18b5-4e12-a159-271043efb2b1"
    }
}

In this section:

Documentation

Add Contact to Wallet

Note

Parameters

Request Path Parameters

Request Header Parameters

Request Body Parameters

Note

Response Parameters

Search results