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

# Wallet Transfer Recipient Lookup

Used to retrieve the `account_id` of the account for transfering funds.

<br />

### Overview

Two queries for looking up recipients for transfer operations:

* `lookupUser` - Find a user by phone or email
* `lookupBusiness` - Find businesses by company name

***

### lookupUser

Look up an individual user recipient.

#### Query (UserLookupInput)

```graphql theme={null}
lookupUser(input: UserLookupInput!): UserLookupResult!
```

**Requires**: `QUERY_RECIPIENT` scope.

#### Input

| Field       | Type   | Required | Description                                                            |
| :---------- | :----- | :------- | :--------------------------------------------------------------------- |
| phoneNumber | String | No\*     | The phone number of the recipient in E.164 format (e.g., +14155551234) |
| email       | String | No\*     | The email address of the recipient                                     |

*Provide exactly one field*

#### Response (UserLookupResult)

| Field       | Type    | Description                  |
| :---------- | :------ | :--------------------------- |
| recipientId | UUID!   | Recipient's account IDl      |
| displayName | String! | Display name ("First Last")) |

#### Examples

**By phone:**

```graphql theme={null}
query {
  lookupUser(input: { phoneNumber: "+14155551234" }) {
    recipientId
    displayName
  }
}
```

**By email:**

```graphql theme={null}
query {
  lookupUser(input: { email: "jane@example.com" }) {
    recipientId
    displayName
  }
}
```

**Success:**

```json theme={null}
{
  "data": {
    "lookupUser": {
      "recipientId": "a2c02ec6-357b-41cf-9229-4da34e727019",
      "displayName": "John Doe"
    }
  }
}
```

**Not found:**

```json theme={null}
{
  "errors": [{
    "message": "No recipient found with the provided information.",
    "extensions": { "code": "RC-0001" }
  }]
}
```

#### Error Codes

| Code    | Description             |
| :------ | :---------------------- |
| RC-0001 | Recipient not found     |
| RC-0002 | Multiple matches (rare) |
| AR-0001 | Invalid/missing input   |
| GE-9999 | Server error            |

***

### lookupBusiness

Look up business recipients by company name.

#### Query

```graphql theme={null}
lookupBusiness(input: BusinessLookupInput!): [BusinessLookupResult!]!
```

**Requires**: `QUERY_RECIPIENT` scope.

#### Input

| Field       | Type   | Required | Description                                  |
| :---------- | :----- | :------- | :------------------------------------------- |
| companyName | String | Yes      | Company name (case-insensitive, exact match) |

**Note:** Searches both registered business name and DBA name. Must match exactly (case-insensitive).

#### Response

| Field       | Type    | Description                                         |
| :---------- | :------ | :-------------------------------------------------- |
| recipientId | UUID!   | Recipient's account IDl                             |
| displayName | String! | Display name (DBA if available, else company name)) |
| companyName | String! | Formatted name: "Company Name (DBA Name)"           |
| state       | String  | State from business legal address                   |

#### Examples

```graphql theme={null}
query {
  lookupBusiness(input: { companyName: "acme corporation" }) {
    recipientId
    displayName
    companyName
    state
  }
}
```

**Single match:**

```json theme={null}
{
  "data": {
    "lookupBusiness": [
      {
        "recipientId": "c4e24ge8-579d-63eh-b451-6fc56g949241",
        "displayName": "Acme Corporation",
        "companyName": "Acme Corporation",
        "state": "CA"
      }
    ]
  }
}
```

**Multiple matches (same name, different DBAs):**

```json theme={null}
{
  "data": {
    "lookupBusiness": [
      {
        "recipientId": "c4e24ge8-579d-63eh-b451-6fc56g949241",
        "displayName": "Acme Retail",
        "companyName": "Acme Corporation (Acme Retail)",
        "state": "CA"
      },
      {
        "recipientId": "d5f35hf9-680e-74fi-c562-7gd67h050352",
        "displayName": "Acme Wholesale",
        "companyName": "Acme Corporation (Acme Wholesale)",
        "state": "NY"
      }
    ]
  }
}
```

**Not found:**

```json theme={null}
{
  "errors": [{
    "message": "No recipient found with the provided information.",
    "extensions": { "code": "RC-0001" }
  }]
}
```

#### Error Codes

| Code    | Description           |
| :------ | :-------------------- |
| RC-0001 | Recipient not found   |
| AR-0001 | Invalid/missing input |
| GE-9999 | Server error          |

***

<br />

### Important Notes

#### lookupUser

* Phone numbers must be in E.164 format (e.g., +14155551234)
* 10-digit US numbers are auto-normalized
* Email is case-insensitive
* Throws error if not found

### lookupBusiness

* Case-insensitive exact match - "acme corporation" matches "ACME CORPORATION" or "Acme Corporation"
* Searches both business name and DBA name
* Returns array (may contain multiple businesses with the same name)
* Throws error if no matches found
* `companyName` is formatted as "Business Name (DBA Name)" when DBA differs from business name