> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lomadee.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Affiliates

> Affiliate resource client for partner affiliate operations

Access through `sdk.affiliates` on a [`Lomadee`](/docs/sdk/reference/client) instance. Import types from `@thelomadee/sdk/domains`.

```typescript theme={null}
import type {
  AffiliateQuery,
  AffiliateListResponse,
  AffiliateListItem,
  AffiliateCluster,
  SignUpBody,
  UpdateAffiliateBody,
  AffiliateResponse,
  AffiliateInviteStatus,
  DocumentType,
} from '@thelomadee/sdk/domains';
import type { SdkResponse } from '@thelomadee/sdk';
```

<Warning>
  Signup and affiliate payloads include PII and financial data (documents, bank accounts, PIX). Collect, transmit, and store them only on the server with appropriate access controls and compliance measures.
</Warning>

## `list`

```typescript theme={null}
list(query: AffiliateQuery): Promise<AffiliateListResponse>
```

### Parameters — `AffiliateQuery`

<ParamField query="search" type="string">
  Optional search string.
</ParamField>

<ParamField query="page" type="number">
  Optional page index.
</ParamField>

<ParamField query="limit" type="number">
  Optional page size.
</ParamField>

<ParamField query="affiliateIds" type="string[]">
  Optional filter by affiliate identifiers.
</ParamField>

### Returns

`Promise<AffiliateListResponse>` — `{ data: AffiliateListItem[]; count: number }`.

### Example

```typescript theme={null}
const { data, count } = await sdk.affiliates.list({ page: 1, limit: 20 });
```

***

## `get`

```typescript theme={null}
get(id: string): Promise<AffiliateResponse>
```

<ParamField path="id" type="string" required>
  Affiliate identifier.
</ParamField>

### Returns

`Promise<AffiliateResponse>` — not wrapped in `SdkResponse`.

***

## `create`

```typescript theme={null}
create(body: SignUpBody): Promise<SdkResponse<AffiliateResponse>>
```

Creates an affiliate via the SDK signup flow (`SignUpBody`).

### Parameters — `SignUpBody`

<ParamField body="user" type="UserSignUpBody" required>
  User profile for signup. See [UserSignUpBody](#usersignupbody).
</ParamField>

<ParamField body="address" type="UserAddressBody" required>
  Postal address. See [UserAddressBody](#useraddressbody).
</ParamField>

<ParamField body="bank" type="UserBankBody" required>
  Bank details. See [UserBankBody](#userbankbody).
</ParamField>

### Returns

`Promise<SdkResponse<AffiliateResponse>>` — `{ data: AffiliateResponse }`.

***

## `update`

```typescript theme={null}
update(id: string, body: UpdateAffiliateBody): Promise<AffiliateResponse>
```

<ParamField path="id" type="string" required>
  Affiliate identifier.
</ParamField>

### Parameters — `UpdateAffiliateBody`

<ParamField body="user" type="UpdateUserBody">
  Optional partial user fields. See [UpdateUserBody](#updateuserbody).
</ParamField>

<ParamField body="address" type="UserAddressBody">
  Optional address replacement. See [UserAddressBody](#useraddressbody).
</ParamField>

<ParamField body="bank" type="UserBankBody">
  Optional bank details. See [UserBankBody](#userbankbody).
</ParamField>

### Returns

`Promise<AffiliateResponse>`.

***

## `DocumentType`

Union type used in signup and user models:

`'cpf' | 'cnpj' | 'rg' | 'international' | 'passport'`

## `AffiliateInviteStatus`

Union type for affiliate invite state (dashboard-api enum):

| Value             | Description       |
| ----------------- | ----------------- |
| `'pendent'`       | Invite pending    |
| `'accept'`        | Invite accepted   |
| `'need_approval'` | Awaiting approval |
| `'rejected'`      | Invite rejected   |

## `UserSignUpBody`

<ParamField body="username" type="string" required>
  Username.
</ParamField>

<ParamField body="phone" type="string">
  Optional phone number.
</ParamField>

<ParamField body="email" type="string" required>
  Email address.
</ParamField>

<ParamField body="fullName" type="string" required>
  Full legal name.
</ParamField>

<ParamField body="birthDate" type="string" required>
  Birth date (string format not specified in SDK types).
</ParamField>

<ParamField body="documentType" type="DocumentType" required>
  Document type union.
</ParamField>

<ParamField body="document" type="string" required>
  Document number.
</ParamField>

<ParamField body="pis" type="string">
  Optional PIS identifier.
</ParamField>

<ParamField body="legalName" type="string">
  Optional legal entity name.
</ParamField>

<ParamField body="tradeName" type="string">
  Optional trade name.
</ParamField>

## `UserAddressBody`

<ParamField body="country" type="string">
  Optional country. Comment in SDK source: default `brazil` (default behavior is not enforced by the SDK type).
</ParamField>

<ParamField body="postalCode" type="string" required>
  Postal code.
</ParamField>

<ParamField body="street" type="string" required>
  Street name.
</ParamField>

<ParamField body="number" type="string" required>
  Street number.
</ParamField>

<ParamField body="complement" type="string">
  Optional address complement.
</ParamField>

<ParamField body="neighbourhood" type="string" required>
  Neighbourhood.
</ParamField>

<ParamField body="city" type="string" required>
  City.
</ParamField>

<ParamField body="state" type="string" required>
  State.
</ParamField>

## `UserBankBody`

<ParamField body="country" type="string">
  Optional country. Comment in SDK source: default `brazil`.
</ParamField>

<ParamField body="brazilBank" type="BrazilBankBody">
  Brazilian bank account. See [BrazilBankBody](#brazilbankbody).
</ParamField>

<ParamField body="internationalBank" type="InternationalBankBody">
  International bank account. See [InternationalBankBody](#internationalbankbody).
</ParamField>

## `BrazilBankBody`

<Warning>
  Contains sensitive financial and identity-related fields. Never log full bank or PIX details.
</Warning>

<ParamField body="brazilBankId" type="string" required>
  Brazilian bank identifier.
</ParamField>

<ParamField body="agency" type="string" required>
  Agency number.
</ParamField>

<ParamField body="agencyDigit" type="string" required>
  Agency check digit.
</ParamField>

<ParamField body="account" type="string" required>
  Account number.
</ParamField>

<ParamField body="accountDigit" type="string" required>
  Account check digit.
</ParamField>

<ParamField body="accountType" type="'CHECKING' | 'SAVINGS'" required>
  Account type union.
</ParamField>

<ParamField body="name" type="string" required>
  Account holder name.
</ParamField>

<ParamField body="pix" type="string" required>
  PIX key value.
</ParamField>

<ParamField body="pixType" type="string" required>
  PIX key type (string; allowed values not enumerated in SDK types).
</ParamField>

## `InternationalBankBody`

<Warning>
  Contains sensitive financial data. Never log full account, IBAN, or routing details.
</Warning>

<ParamField body="id" type="string" required>
  International bank record identifier.
</ParamField>

<ParamField body="bankName" type="string" required>
  Bank name.
</ParamField>

<ParamField body="bankCountry" type="string" required>
  Bank country.
</ParamField>

<ParamField body="bankAddress" type="string" required>
  Bank address.
</ParamField>

<ParamField body="beneficiaryName" type="string" required>
  Beneficiary name.
</ParamField>

<ParamField body="accountNumber" type="string" required>
  Account number.
</ParamField>

<ParamField body="iban" type="string" required>
  IBAN.
</ParamField>

<ParamField body="swiftBic" type="string" required>
  SWIFT/BIC code.
</ParamField>

<ParamField body="sortCode" type="string" required>
  Sort code.
</ParamField>

<ParamField body="abaRoutingNumber" type="string" required>
  ABA routing number.
</ParamField>

<ParamField body="paymentDetails" type="string" required>
  Payment details.
</ParamField>

<ParamField body="intermediaryBankName" type="string" required>
  Intermediary bank name.
</ParamField>

<ParamField body="intermediaryBankSwift" type="string" required>
  Intermediary bank SWIFT.
</ParamField>

<ParamField body="intermediaryBankAddress" type="string" required>
  Intermediary bank address.
</ParamField>

## `UpdateUserBody`

All fields optional:

<ParamField body="username" type="string">
  Username.
</ParamField>

<ParamField body="phone" type="string">
  Phone number.
</ParamField>

<ParamField body="birthDate" type="string">
  Birth date.
</ParamField>

<ParamField body="documentType" type="DocumentType">
  Document type union.
</ParamField>

<ParamField body="document" type="string">
  Document number.
</ParamField>

<ParamField body="pis" type="string">
  PIS identifier.
</ParamField>

<ParamField body="legalName" type="string">
  Legal entity name.
</ParamField>

<ParamField body="tradeName" type="string">
  Trade name.
</ParamField>

## `AffiliateResponse`

<Warning>
  Response `user` may contain PII (email, document, phone, address). Handle and log accordingly.
</Warning>

<ParamField body="id" type="string" required>
  Affiliate identifier.
</ParamField>

<ParamField body="user" type="User" required>
  User record. Address is nested on `user`, not at the top level. See [User](#user).
</ParamField>

<ParamField body="userOrganizationId" type="string">
  Optional user-organization identifier.
</ParamField>

<ParamField body="inviteStatus" type="AffiliateInviteStatus | null">
  Optional invite status, or `null`. See [AffiliateInviteStatus](#affiliateinvitestatus).
</ParamField>

<ParamField body="inviteHash" type="string | null">
  Optional invite hash, or `null`.
</ParamField>

<ParamField body="active" type="boolean">
  Optional active flag.
</ParamField>

## `AffiliateListItem`

Extends `AffiliateResponse` with cluster membership for list results.

<ParamField body="clusters" type="AffiliateCluster[]" required>
  Clusters the affiliate belongs to. See [AffiliateCluster](#affiliatecluster).
</ParamField>

## `AffiliateListResponse`

<ParamField body="data" type="AffiliateListItem[]" required>
  Page of affiliate list items.
</ParamField>

<ParamField body="count" type="number" required>
  Total count for the query.
</ParamField>

## `AffiliateCluster`

<ParamField body="id" type="string" required>
  Cluster identifier.
</ParamField>

<ParamField body="name" type="string" required>
  Cluster name.
</ParamField>

<ParamField body="isDefault" type="boolean" required>
  Default cluster flag.
</ParamField>

<ParamField body="active" type="boolean" required>
  Active flag.
</ParamField>

<ParamField body="affiliateCount" type="number" required>
  Affiliate count field from API.
</ParamField>

<ParamField body="affiliatesCount" type="number" required>
  Affiliates count field from API.
</ParamField>

<ParamField body="createdAt" type="string" required>
  Creation timestamp.
</ParamField>

<ParamField body="updatedAt" type="string" required>
  Update timestamp.
</ParamField>

## `User`

<Warning>
  May contain PII. Optional fields reflect mapper optional chaining in the SDK types.
</Warning>

<ParamField body="id" type="string">
  Optional user identifier.
</ParamField>

<ParamField body="email" type="string">
  Optional email address.
</ParamField>

<ParamField body="username" type="string">
  Optional username.
</ParamField>

<ParamField body="document" type="string">
  Optional document number.
</ParamField>

<ParamField body="documentType" type="DocumentType">
  Optional document type union.
</ParamField>

<ParamField body="onboardingStatus" type="'Completed' | 'Pending'">
  Optional onboarding status.
</ParamField>

<ParamField body="avatar" type="string | null">
  Optional avatar URL or `null`.
</ParamField>

<ParamField body="birthDate" type="string">
  Optional birth date.
</ParamField>

<ParamField body="phone" type="string">
  Optional phone number.
</ParamField>

<ParamField body="createdAt" type="string">
  Optional creation timestamp.
</ParamField>

<ParamField body="updatedAt" type="string">
  Optional update timestamp.
</ParamField>

<ParamField body="address" type="Address | null">
  Optional nested address, or `null`. See [Address](#address).
</ParamField>

<ParamField body="pis" type="string">
  Optional PIS identifier.
</ParamField>

<ParamField body="categories" type="unknown">
  Optional categories payload (shape not specified in SDK types).
</ParamField>

<ParamField body="tradeName" type="string">
  Optional trade name.
</ParamField>

<ParamField body="legalName" type="string">
  Optional legal entity name.
</ParamField>

<ParamField body="position" type="string">
  Optional position.
</ParamField>

<ParamField body="lastLoginAt" type="string">
  Optional last login timestamp.
</ParamField>

<ParamField body="accessCount" type="number">
  Optional access count.
</ParamField>

## `Address`

Response address model. All fields optional in SDK types.

<ParamField body="id" type="string">
  Address identifier.
</ParamField>

<ParamField body="country" type="string">
  Country.
</ParamField>

<ParamField body="cep" type="string">
  Postal code (CEP).
</ParamField>

<ParamField body="address" type="string">
  Street address line.
</ParamField>

<ParamField body="number" type="string">
  Street number.
</ParamField>

<ParamField body="complement" type="string">
  Address complement.
</ParamField>

<ParamField body="neighbourhood" type="string">
  Neighbourhood.
</ParamField>

<ParamField body="state" type="string">
  State.
</ParamField>

<ParamField body="city" type="string">
  City.
</ParamField>

## Example

```typescript theme={null}
import type { SignUpBody } from '@thelomadee/sdk/domains';

const body: SignUpBody = {
  user: {
    username: 'partner-user',
    email: 'user@example.com',
    fullName: 'Example User',
    birthDate: '1990-01-01',
    documentType: 'cpf',
    document: '00000000000',
  },
  address: {
    postalCode: '01310100',
    street: 'Example Street',
    number: '100',
    neighbourhood: 'Centro',
    city: 'São Paulo',
    state: 'SP',
  },
  bank: {
    brazilBank: {
      brazilBankId: 'bank-id',
      agency: '0001',
      agencyDigit: '0',
      account: '12345',
      accountDigit: '6',
      accountType: 'CHECKING',
      name: 'Example User',
      pix: 'user@example.com',
      pixType: 'email',
    },
  },
};

const { data: affiliate } = await sdk.affiliates.create(body);
```

## Related

* [Client](/docs/sdk/reference/client)
* [Environments and secrets](/docs/sdk/guides/environments-and-secrets)
* [Error handling](/docs/sdk/guides/error-handling)