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
  }'

Tax authority connection

Connect your organization’s NRS (Nigeria Revenue Service) taxpayer identity. Required before submitting invoices to the tax authority in production. You can finalise invoices and send them to buyers without a connection — only submission requires it.

Get tax authority connection

GET /a/v1/organizations/:orgId/tax-registration

Get your organization’s current tax authority connection status. Returns null if no connection exists.

bash

curl https://gateway.useyona.com/a/v1/organizations/9f8e7d6c-5b4a-3210-fedc-ba9876543210/tax-registration \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Status	Code	Trigger
404	RES001	Organization not found

Connect tax authority

PUT /a/v1/organizations/:orgId/tax-registration

Connect or update your NRS taxpayer identity. Verifies the credentials with the tax authority before marking the connection as connected. If verification fails, the connection remains pending and the error reason is returned. The nrsServiceId is an 8-character identifier assigned by NRS — find it in your NRS MBS portal.

Request body

Field	Type	Required	Description
`nrsBusinessId`	string	Yes	Business ID assigned by FIRS. Found in your NRS MBS portal under your taxpayer profile after authorizing Yona as your Access Point.
`nrsServiceId`	string	Yes	8-character Service ID assigned by FIRS when you authorize an Access Point. Found in your NRS MBS portal under “Authorized Applications.”
`irnTemplate`	string	No	Custom IRN format. Default: `{{invoice_id}}-{ServiceID}-{{YYYYMMDD}}`. Most users don’t need to change this.

bash

curl -X PUT https://gateway.useyona.com/a/v1/organizations/9f8e7d6c-5b4a-3210-fedc-ba9876543210/tax-registration \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "nrsBusinessId": "BUS-NG-12345",
    "nrsServiceId": "94ND90NR"
  }'

Status	Code	Trigger
400	TAX001	Verification with tax authority failed
400	VAL001	Invalid or missing fields
404	RES001	Organization not found

Revoke connection

POST /a/v1/organizations/:orgId/tax-registration/revoke

Revoke the tax authority connection. Invoice submission will be blocked until reconnected. Finalising and sending to buyers are unaffected. No request body.

bash

curl -X POST https://gateway.useyona.com/a/v1/organizations/9f8e7d6c-5b4a-3210-fedc-ba9876543210/tax-registration/revoke \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Status	Code	Trigger
404	RES001	Organization or connection not found

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
`GET`	`/a/v1/organizations/:orgId/tax-registration`	Get tax authority connection
`PUT`	`/a/v1/organizations/:orgId/tax-registration`	Connect/update tax authority
`POST`	`/a/v1/organizations/:orgId/tax-registration/revoke`	Revoke tax authority connection