Recipient Object Specifications

The Recipient object contains the necessary information for card issuance. All fields must adhere to specific validation rules to ensure data integrity and compliance.

Required Fields

participantId

• Type: String
• Length: 1-20 characters
• Purpose: Unique identifier for the recipient
• Example: "USER123456"

firstName

• Type: String
• Length: 1-50 characters
• Format: Alphabetic characters
• Example: "John"

lastName

• Type: String
• Length: 1-50 characters
• Format: Alphabetic characters
• Example: "Doe"

address1

• Type: String
• Length: 1-50 characters
• Purpose: Primary address line
• Example: "123 Main Street"

city

• Type: String
• Length: 1-35 characters
• Example: "San Francisco"

state

• Type: String
• Length: 1-50 characters
• For US: Use two-letter state code
• For international: Use appropriate region/province
• Example: "CA"

postalCode

• Type: String
• Length: 1-20 characters
• Format: Supports both US ZIP codes and international postal codes
• Example: "94105"

countryCode

• Type: String
• Length: Exactly 3 characters
• Format: ISO 3166-1 alpha-3 country code
• Example: "USA"

emailAddress

• Type: String
• Length: 1-80 characters
• Format: Valid email address format
• Example: "john.doe@example.com"

mobilePhone

• Type: String
• Length: 1-20 characters
• Format: Valid phone number without country code
• Example: "4155551234"

language

• Type: String
• Length: 2-5 characters
• Format: IETF language tag
• Default: "en-US"
• Example: "en-US", "es-MX"

Optional Fields

address2

• Type: String
• Length: 1-50 characters (when provided)
• Purpose: Secondary address line (apartment, suite, etc.)
• Example: "Suite 500"

Example Object

{
  "participantId": "USER123456",
  "firstName": "John",
  "lastName": "Doe",
  "address1": "123 Main Street",
  "address2": "Suite 500",
  "city": "San Francisco",
  "state": "CA",
  "postalCode": "94105",
  "countryCode": "USA",
  "emailAddress": "john.doe@example.com",
  "mobilePhone": "4155551234",
  "language": "en-US"
}

Validation Rules

1. All string fields must be trimmed of leading/trailing whitespace
2. Country codes must be in ISO 3166-1 alpha-3 format (e.g., "USA", "CAN", "GBR")
3. Phone numbers should not include:
   • Country code
   • Special characters (except for optional hyphens)
   • Spaces
4. Email addresses must be:
   • Valid format (username@domain.tld)
   • Maximum 80 characters
   • Case-insensitive
5. Language codes must follow IETF language tag format:
   • Two-letter language code (ISO 639-1)
   • Optional country/region code
   • Example: "en-US", "es-MX", "fr-FR"

Error Handling

The API will return validation errors with specific messages when:

• Required fields are missing
• Field lengths exceed specified limits
• Formats are invalid (email, phone, country code)
• Invalid characters are used

All error responses will include:

• HTTP 400 status code
• Detailed error message
• Field name that failed validation