POST /v1/onboarding — register a business entity

Register a business to unlock wallet creation. Accepts businessName, contactEmail, and contactPhone. Returns a businessId for subsequent API calls.

Register a business entity under your Axis account to unlock wallet creation and agent payment infrastructure. You must complete this step before you can create wallets or fund autonomous agents. On success, Axis returns a businessId — keep it safe, as it is required for all wallet and agent operations.

Endpoints

Both routes are equivalent and route to the same handler:

POST /v1/onboarding
POST /api/onboarding

Authentication

A valid JWT session token is required. Pass it in the Authorization header:

Authorization: Bearer <token>

Obtain a token by calling POST /v1/auth/login.

Request Body

businessName · string · required

The legal or trading name of the business. Must be between 2 and 200 characters.

contactEmail · string · required

A valid contact email address for the business.

contactPhone · string

An optional contact phone number for the business. Recommended format: E.164 (e.g. [phone]).

Request Example

{
  "businessName": "Acme Corp",
  "contactEmail": "[e-mail]",
  "contactPhone": "[phone]"
}

Response — 201 Created

status · string

Always "success" for a successful response.

data · object

The registered business record.

Show data fields

data.businessId · string

Unique UUID identifying the registered business. Store this value — it is required for wallet creation and all subsequent business-scoped API calls.

data.name · string

The business name as registered.

data.contactEmail · string

The contact email address associated with the business.

data.contactPhone · string

The contact phone number, if provided.

data.createdAt · string

ISO 8601 timestamp of when the business was registered.

{
  "status": "success",
  "data": {
    "businessId": "b1a2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Acme Corp",
    "contactEmail": "[e-mail]",
    "contactPhone": "[phone]",
    "createdAt": "2026-07-21T09:00:00.000Z"
  }
}

Save the businessId immediately. It is not re-displayed after this response and is required to create wallets and configure autonomous agents on your account. Store it in your environment variables or a secure configuration store.

Error Responses

400 — Validation Error

Returned when one or more request fields fail validation.

{
  "status": "error",
  "errors": [
    {
      "code": "too_small",
      "minimum": 2,
      "type": "string",
      "inclusive": true,
      "exact": false,
      "path": ["businessName"],
      "message": "String must contain at least 2 character(s)"
    },
    {
      "code": "invalid_string",
      "validation": "email",
      "path": ["contactEmail"],
      "message": "Invalid email"
    }
  ]
}

401 — Unauthorized

Returned when the Authorization header is missing or the token is invalid or expired.

{
  "status": "error",
  "message": "Unauthorized"
}