Client payload | 21yield Developers

What It Does

Use category: "client" to create, update, or delete individual and company clients. Create clients before sending disbursements that reference them.

Field Summary

Required Fields

Field	Required	Notes
`client_id`	Always	Unique client identifier.
`step`	Always	`create`, `update`, or `delete`.
`name`	Create	Client name.
`email`	Create	Client email address.
`phone`	Create	Client phone number.
`address`	Create	Client address.
`country`	Create	ISO 3166-1 alpha-2 country code, for example `US`.
`is_company`	Create	`true` for company clients, `false` for individual clients.
`registration_number`	Create	ID card or passport for an individual; company registration for a company.
`gender`	Individual create	Required unless `is_company` is `true`.
`contact_person`	Company create	Required when `is_company` is `true`.

Common optional fields:

Field	Notes
`info`	Additional structured metadata.

country must be ISO 3166-1 alpha-2, for example US, GB, FR, or BR.

gender accepts male, female, or company. For company clients, omit gender or send company; the worker stores company clients with gender = "company".

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

Create 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",
    "info": {
      "key": "value"
    }
  }
}

Update

Send step: "update" with the same client_id and fields to change.

{
  "category": "client",
  "data": {
    "client_id": "BR-2024-001",
    "step": "update",
    "email": "new.email@example.com",
    "phone": "+1234567899"
  }
}

Delete

{
  "category": "client",
  "data": {
    "client_id": "BR-2024-001",
    "step": "delete"
  }
}

Notes

A client is either individual or company, controlled by is_company.
Company clients require contact_person; gender may be omitted and is stored as company.
Individual clients must not use gender: "company".
Use stable client_id values; other payloads reference clients by id.
Send assigned uppercase country codes. Unknown payload fields and caller-supplied content_hash are rejected; info remains available for metadata.
Duplicate creates return 409; missing updates return 404. Hash-matching updates return 200 unchanged without domain timestamp changes.
Exact retries replay the original status/body. Use ingestion retry guidance, not a generic duplicate-response check.