Buyers API

Base path: https://gateway.useyona.com/i/v1/buyers

A buyer is the entity receiving invoices. Same structure as Sellers with two differences: taxNumber is optional (supporting B2C), and default partyType is individual.

Create buyer

POST /i/v1/buyers

Request body

Field	Type	Required	Description
`partyName`	string	Yes	Name, max 255 chars
`tradingName`	string	No	Trading/brand name, max 255 chars
`partyType`	string	No	`individual` \| `company` \| `partnership` \| `non_profit` \| `government`. Default: `individual`
`taxNumber`	string	No	Tax ID, max 50 chars. Optional for B2C.
`email`	string	Yes	Valid email
`phoneNumber`	string	Yes	Valid phone number
`postalAddress`	object	Yes	Must include `line1`, `city`, `country` (ISO 2-letter)
`notes`	string	No	Max 1000 chars

bash

curl -X POST https://gateway.useyona.com/i/v1/buyers \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "partyName": "Kalu & Associates Ltd",
    "email": "procurement@kaluassociates.ng",
    "phoneNumber": "+2349087654321",
    "taxNumber": "87654321-0001",
    "postalAddress": {
      "line1": "27 Wuse II District",
      "city": "Abuja",
      "state": "FCT",
      "country": "NG"
    }
  }'

Status	Code	Trigger
400	VAL001	Missing or invalid required fields

List buyers

GET /i/v1/buyers

bash

curl "https://gateway.useyona.com/i/v1/buyers?page=1&limit=20" \
  -H "Authorization: Bearer sk_test_your_key_here"

Get buyer

GET /i/v1/buyers/:id

bash

curl https://gateway.useyona.com/i/v1/buyers/d8b2e4f6-9a3c-5b7d-0e1f-2a3b4c5d6e7f \
  -H "Authorization: Bearer sk_test_your_key_here"

Status	Code	Trigger
404	RES001	Buyer not found

Update buyer

PATCH /i/v1/buyers/:id

bash

curl -X PATCH https://gateway.useyona.com/i/v1/buyers/d8b2e4f6-9a3c-5b7d-0e1f-2a3b4c5d6e7f \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "email": "accounts@kaluassociates.ng" }'

Status	Code	Trigger
400	VAL001	Invalid field values
404	RES001	Buyer not found

Delete buyer

DELETE /i/v1/buyers/:id

bash

curl -X DELETE https://gateway.useyona.com/i/v1/buyers/d8b2e4f6-9a3c-5b7d-0e1f-2a3b4c5d6e7f \
  -H "Authorization: Bearer sk_test_your_key_here"

Bulk delete buyers

DELETE /i/v1/buyers/bulk

bash

curl -X DELETE https://gateway.useyona.com/i/v1/buyers/bulk \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "ids": ["d8b2e4f6-9a3c-5b7d-0e1f-2a3b4c5d6e7f"] }'

Search buyers

GET /i/v1/buyers/search

bash

curl "https://gateway.useyona.com/i/v1/buyers/search?q=Kalu" \
  -H "Authorization: Bearer sk_test_your_key_here"

Verify tax number

POST /i/v1/buyers/:id/verify-tax-number

bash

curl -X POST https://gateway.useyona.com/i/v1/buyers/d8b2e4f6-9a3c-5b7d-0e1f-2a3b4c5d6e7f/verify-tax-number \
  -H "Authorization: Bearer sk_test_your_key_here"

Get verification status

GET /i/v1/buyers/:id/verification-status

bash

curl https://gateway.useyona.com/i/v1/buyers/d8b2e4f6-9a3c-5b7d-0e1f-2a3b4c5d6e7f/verification-status \
  -H "Authorization: Bearer sk_test_your_key_here"