Receiver Query API

Query and discover receiver organizations in the Versa network.

Overview

All Versa receivers are registered clients that have been verified during our onboarding process. Since sender registration requires explicitly identifying receivers, the Receiver Query API enables you to:

• Discover verified receiver organizations in the network
• Filter receivers by business category (expense management, duty of care)
• Check routing status for specific customer handles
• Get receiver details needed for sender registration

Querying

Search available receivers with optional filtering.

curl --request POST \
  --url 'https://registry.versa.org/receiver/query' \
  --header 'Authorization: Basic CLIENT_ID:CLIENT_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "filters": [
      {
        "category": ["expense"]
      }
    ],
    "handles": {
      "customer_email_domain": "acme.com"
    }
  }'

Request Parameters

Field	Type	Description
filters	array	Optional. Array of filter objects to limit results
handles	object	Optional. Transaction handles for routing queries

Filter Object

Field	Type	Description
category	array	Filter by receiver categories: expense, duty_of_care, firehose
region	array	Filter by geographic regions (future use)

Handles Object

Field	Type	Description
customer_email	nullable string	Specific customer email (e.g., 'jane@acme.com')
customer_email_domain	nullable string	Customer’s email domain (e.g., 'acme.com')
merchant_group_code	nullable string	Merchant-specific identifier for corporate entity
merchant_user_code	nullable string	Merchant-specific identifier for individual user

Response Format

{
  "mode": "prod",
  "receivers": [
    {
      "org": {
        "id": "org_3bc773e74919435bad07c2e9473dfbb4",
        "name": "EZ Expense",
        "legal_name": "EZ Expense Inc.",
        "slug": "ez-expense",
        "website": "https://ez-expense.example.com",
        "logo": "https://ez-expense.example.com/assets/logo.png",
        "brand_color": "#FF5733",
        "stock_symbol": null,
        "twitter": null,
        "isin": null,
        "lei": null,
        "naics": "522320",
        "vat_number": null
      },
      "category": "expense",
      "handling": {
        "sender_registered": true,
        "receiver_registered": false
      }
    }
  ]
}

Response Fields

Field	Type	Description
mode	enum	Environment mode: test or prod
receivers	array	Array of receiver objects

Receiver Query Result

Field	Type	Description
org	object	Organization details
category	enum	Receiver category: expense, duty_of_care, or firehose
handling	object	Handling status (only present when handles provided)

Org

Field	Type	Description
id	string	Unique Versa ID for the receiver
name	string	Organization display name
legal_name	nullable string	Legal business name
slug	string	URL-friendly identifier
website	string	Organization website
logo	nullable string	Logo URL
brand_color	nullable string	Brand color in hex format
stock_symbol	nullable string	Stock ticker symbol
twitter	nullable string	Twitter handle
isin	nullable string	International Securities Identification Number
lei	nullable string	Legal Entity Identifier
naics	nullable string	North American Industry Classification System
vat_number	nullable string	VAT registration number

Handling Object

Field	Type	Description
sender_registered	boolean	true if sender has registered the provided handles to this receiver
receiver_registered	boolean	true if receiver has registered the provided handles

Common Use Cases

Query All Receivers

Get a list of all available receivers without any filters:

curl --request POST \
  --url 'https://registry.versa.org/receiver/query' \
  --header 'Authorization: Basic CLIENT_ID:CLIENT_SECRET'

Query by Category

Find all expense management receivers:

curl --request POST \
  --url 'https://registry.versa.org/receiver/query' \
  --header 'Authorization: Basic CLIENT_ID:CLIENT_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "filters": [
      {
        "category": ["expense"]
      }
    ]
  }'

Check Routing Status

Query receivers and check if they’re configured to receive receipts for a specific customer domain:

curl --request POST \
  --url 'https://registry.versa.org/receiver/query' \
  --header 'Authorization: Basic CLIENT_ID:CLIENT_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "handles": {
      "customer_email_domain": "acme.com"
    }
  }'

The response will include handling information for each receiver, showing whether routing is configured.

Combined Query

Filter by category and check routing status simultaneously:

curl --request POST \
  --url 'https://registry.versa.org/receiver/query' \
  --header 'Authorization: Basic CLIENT_ID:CLIENT_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "filters": [
      {
        "category": ["expense", "duty_of_care"]
      }
    ],
    "handles": {
      "customer_email": "john.doe@acme.com",
      "merchant_group_code": "ACME123"
    }
  }'

Receiver Categories

• expense: Expense management platforms that process receipts for business expense tracking and reimbursement
• duty_of_care: Travel safety and security providers that help organizations fulfill their duty of care obligations
• firehose: A unique category that applies only in test for the Sandbox Firehose receiver

Testing

For testing purposes, you can query receivers using test credentials. The sandbox environment includes test receivers that you can use for development:

curl --request POST \
  --url 'https://registry.versa.org/receiver/query' \
  --header 'Authorization: Basic TEST_CLIENT_ID:TEST_CLIENT_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "handles": {
      "customer_email_domain": "sandbox-firehose.versa.org"
    }
  }'