Organizations

Base path: https://gateway.useyona.com/a/v1/organizations

An organization is your business entity on Yona. It holds your subscription, credit pool, team members, and API keys. B2B2B platforms can create child organizations to manage multiple businesses under one account.

Create organization

POST /a/v1/organizations

Create a new organization or child organization (for B2B2B platforms).

Request body

Field	Type	Required	Description
`businessName`	string	Yes	Organization name, 2-255 chars
`email`	string	Yes	Contact email
`taxNo`	string	No	Tax number (format: XXXXXXXX-XXXX)
`phoneNumber`	string	No	Contact phone
`website`	string	No	Website URL
`country`	string	No	ISO 2-letter country code

bash

curl -X POST https://gateway.useyona.com/a/v1/organizations \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "businessName": "Lagos Tech Innovations Nigeria Ltd",
    "email": "admin@lagostech.ng",
    "country": "NG"
  }'

Get current organization

GET /a/v1/organizations/me

bash

curl https://gateway.useyona.com/a/v1/organizations/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Update organization

PATCH /a/v1/organizations/me

bash

curl -X PATCH https://gateway.useyona.com/a/v1/organizations/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "businessName": "Zenith Software Solutions Nigeria Ltd",
    "phoneNumber": "+2348012345678"
  }'

Verify tax number

POST /a/v1/organizations/me/onboarding/verify-tax-number

Request body

Field	Type	Required	Description
`taxNo`	string	Yes	Tax number (format: XXXXXXXX-XXXX)

bash

curl -X POST https://gateway.useyona.com/a/v1/organizations/me/onboarding/verify-tax-number \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{ "taxNo": "31245678-0001" }'

Send phone verification

POST /a/v1/organizations/me/onboarding/send-phone-verification

Request body

Field	Type	Required	Description
`phoneNumber`	string	Yes	Phone number to verify

bash

curl -X POST https://gateway.useyona.com/a/v1/organizations/me/onboarding/send-phone-verification \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{ "phoneNumber": "+2348012345678" }'

Verify phone

POST /a/v1/organizations/me/onboarding/verify-phone

Request body

Field	Type	Required	Description
`otp`	string	Yes	OTP received via SMS

bash

curl -X POST https://gateway.useyona.com/a/v1/organizations/me/onboarding/verify-phone \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{ "otp": "482916" }'

Update credit pool config

PATCH /a/v1/organizations/me/credit-pool-config

Configure how credits flow to child organizations (B2B2B).

Request body

Field	Type	Required	Description
`primaryCoversSecondary`	boolean	No	Primary pool pays for all child usage
`fallbackToPrimary`	boolean	No	Child uses own pool first, primary covers shortfall
`minimumReserve`	number	No	Credits to keep in reserve

bash

curl -X PATCH https://gateway.useyona.com/a/v1/organizations/me/credit-pool-config \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "primaryCoversSecondary": true,
    "minimumReserve": 500
  }'

Other organization endpoints

Method	Path	Description
`GET`	`/a/v1/organizations`	List organizations
`GET`	`/a/v1/organizations/:id`	Get organization by ID
`POST`	`/a/v1/organizations/me/onboarding/complete`	Complete onboarding
`POST`	`/a/v1/organizations/switch`	Switch active organization
`GET`	`/a/v1/organizations/me/children`	List child organizations
`GET`	`/a/v1/organizations/me/credit-pool-config`	Get credit pool config