Lookup Recipient

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)

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:

query {
  lookupUser(input: { phoneNumber: "+14155551234" }) {
    recipientId
    displayName
  }
}

By email:

query {
  lookupUser(input: { email: "[email protected]" }) {
    recipientId
    displayName
  }
}

Success:

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

Not found:

{
  "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

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

query {
  lookupBusiness(input: { companyName: "acme corporation" }) {
    recipientId
    displayName
    companyName
    state
  }
}

Single match:

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

Multiple matches (same name, different DBAs):

{
  "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:

{
  "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

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