Client Event FAQ

Overview

Client events manage client information for both individual (person) and company clients.

Required Fields

client_id (string)

Question: What is the client_id?

Answer: A unique identifier for the client. Must be unique across all clients.

Example: "BR-2024-001"

step (string, enum)

Question: What are the valid values for step?

Answer:

• create: Create a new client
• update: Update existing client information
• delete: Delete/remove a client

name (string)

Question: What should I include in the name field?

Answer: The full legal name of the client.

Individual: "John Doe"

Company: "Acme Corporation Inc."

email (string, email)

Question: What format should the email be?

Answer: Must be a valid email address format.

Example: "john.doe@example.com"

phone (string)

Question: What format should phone numbers be?

Answer: Include country code and use international format.

Example: "+1234567890" or "+441234567890"

address (string)

Question: What should I include in the address?

Answer: Complete physical address including street, city, state/province, and postal code.

Example: "123 Main St, New York, NY 10001"

country (string)

Question: What format should the country field be?

Answer: ISO 3166-1 alpha-2 country code (two-letter code). This is the standard two-letter country code used internationally.

Example: "US" (United States), "GB" (United Kingdom), "FR" (France), "BR" (Brazil)

Note: Use the two-letter ISO code. For a complete list of valid country codes, see the country utilities.

is_company (boolean)

Question: When should I set is_company to true?

Answer: Set to true when registering a company client, false for individual clients.

Example: false for individual, true for company

registration_number (string)

Question: What should I provide in registration_number?

Answer:

• For individual clients (is_company: false): Provide ID card number or passport number
• For company clients (is_company: true): Provide official company registration number

Individual Example: "ID-1234567890" or "PASS-AB123456"

Company Example: "CR-2024-001234"

gender (string, enum)

Question: What are the valid values for gender?

Answer:

• "male": For male individual clients
• "female": For female individual clients
• "company": For company clients (must be used when is_company: true)

Example: "male", "female", or "company"

contact_person (string)

Question: When is contact_person required?

Answer: Required when is_company is true. Provides the name of the primary contact person for the company.

Example: "Jane Smith" or "Contact Person Name"

Note: This field is only required for company clients (is_company: true). Individual clients do not need this field.

Optional Fields

info (object)

Question: Can I store additional custom information?

Answer: A flexible object field for storing custom key-value pairs. Use this for any additional metadata specific to your client.

Example:

{
  "info": {
    "key": "value",
    "customField": "customValue"
  }
}

Complete Examples

Individual Client

{
  "category": "client",
  "data": {
    "client_id": "BR-2024-001",
    "step": "create",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "address": "123 Main St, New York, NY 10001",
    "country": "US",
    "is_company": false,
    "registration_number": "ID-1234567890",
    "gender": "male"
  }
}

Company Client

{
  "category": "client",
  "data": {
    "client_id": "BR-2024-002",
    "step": "create",
    "name": "Acme Corporation Inc.",
    "email": "contact@acme.com",
    "phone": "+1234567890",
    "address": "456 Business Ave, New York, NY 10002",
    "country": "US",
    "is_company": true,
    "contact_person": "Jane Smith",
    "registration_number": "CR-2024-001234",
    "gender": "company",
    "info": {
      "key": "value"
    }
  }
}

Common Questions

Q: Can a client have both person and company information?

A: No, you must choose one type using the is_company field. Set is_company: false for individuals, is_company: true for companies.

Q: How do I update client information?

A: Send a new event with step: "update" and the same client_id with updated fields.

Q: Is email validation done?

A: The API validates email format. Invalid emails may be rejected.

Q: Can I change a client from individual to company type?

A: Yes, send an event with step: "update" and modify is_company: true and other key-value.

Q: What happens to loans if I delete a client?

A: Loans are still ongoing, stored an linked to the old client.

Q: What if registration_number is a passport instead of ID card?

A: Both ID card numbers and passport numbers are acceptable for individual clients. Use the document number in the registration_number field.

Q: What gender value should I use for a company?

A: Always use "company" for the gender field when is_company: true.

Field Dependencies

• is_company must be consistent with gender (use "company" when is_company: true)
• contact_person is required when is_company: true
• client_id must be unique
• Email and phone should be verified before use
• Address format should be consistent across systems
• country must be a valid ISO 3166-1 alpha-2 country code (two-letter code)
• registration_number format depends on client type (ID/passport for individuals, company registration for companies)