Buyers

List buyers

GET /i/v1/buyers

buyer.read. Live buyers of the organisation in the token’s mode, filtered by search (name, legal name or tax id) and taxIdStatus; page and limit (up to 100).

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`search`	query	string	No	Name, legal name or tax id. At most 100 characters.
`taxIdStatus`	query	string	No	One of `unverified` \| `pending` \| `verified` \| `not_found` \| `name_mismatch` \| `unavailable` \| `valid_off_network` \| `checking`.
`page`	query	number	No	Default: `1`. At least 1.
`limit`	query	number	No	Default: `20`. Between 1 and 100.

Example request

bash

curl https://gp.useyona.com/i/v1/buyers \
  -H "Authorization: Bearer sk_test_your_key_here"

Responses

One page of buyers, meta.pagination set.

Errors: 400, 401, 403, 429

Create a buyer

POST /i/v1/buyers

buyer.create; charged per buyer before it is saved (refunded if the save fails). A taxId is checked against the jurisdiction’s format and must not be held by another live buyer of the organisation. Status fields (taxIdStatus and the like) cannot be sent: they are set by the verification.

Who can call it: API key or signed-in user.

Request body

Field	Type	Required	Description
`name`	string	Yes	1 to 255 characters.
`legalName`	string or null	No	At most 255 characters.
`taxId`	string or null	No	At most 64 characters.
`taxIdType`	string	No	Defaults to `tin` when a taxId is sent; `none` when there is none. One of `tin` \| `rn` \| `foreign` \| `none`.
`email`	string or null	No	At most 320 characters.
`phone`	string or null	No	E.164.
`address`	object (BuyerAddress) or null	No
`partyType`	string or null	No	One of `individual` \| `company` \| `partnership` \| `non_profit` \| `government`.
`businessDescription`	string or null	No	At most 1000 characters.
`reference`	string or null	No	The tenant’s own reference for this buyer. At most 100 characters.

address

Field	Type	Required	Description
`line1`	string	Yes	1 to 255 characters.
`line2`	string	No	At most 255 characters.
`city`	string	Yes	1 to 100 characters.
`state`	string	No	At most 100 characters.
`lga`	string	No	Local government area. At most 100 characters.
`postalCode`	string	No	At most 20 characters.
`country`	string	Yes	ISO 3166-1 alpha-2.

Example request

bash

curl -X POST https://gp.useyona.com/i/v1/buyers \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "taxId": "12345678-0001",
    "phone": "+2348098765432"
  }'

Responses

The new buyer.

Errors: 400, 401, 402, 403, 409, 429, 503

Get a buyer

GET /i/v1/buyers/{id}

buyer.read. An archived buyer is readable by id (archivedAt set).

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes

Example request

bash

curl https://gp.useyona.com/i/v1/buyers/9f8e7d6c-5b4a-3210-fedc-ba9876543210 \
  -H "Authorization: Bearer sk_test_your_key_here"

Responses

The buyer.

Errors: 400, 401, 403, 404, 429

Update a buyer

PATCH /i/v1/buyers/{id}

buyer.update. The create fields, all optional; an optional field sent as null is cleared, name can be changed but not cleared. Charged only when the edit changes something. A changed tax identity resets the verification.

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes
`Idempotency-Key`	header	string	No	8–128 characters of A–Z, a–z, 0–9, `_` or `-`. A retry with the same key is not charged twice.

Request body

Field	Type	Required	Description
`name`	string	No	1 to 255 characters.
`legalName`	string or null	No	At most 255 characters.
`taxId`	string or null	No	At most 64 characters.
`taxIdType`	string	No	One of `tin` \| `rn` \| `foreign` \| `none`.
`email`	string or null	No	At most 320 characters.
`phone`	string or null	No	E.164.
`address`	object (BuyerAddress) or null	No
`partyType`	string or null	No	One of `individual` \| `company` \| `partnership` \| `non_profit` \| `government`.
`businessDescription`	string or null	No	At most 1000 characters.
`reference`	string or null	No	At most 100 characters.

address

Field	Type	Required	Description
`line1`	string	Yes	1 to 255 characters.
`line2`	string	No	At most 255 characters.
`city`	string	Yes	1 to 100 characters.
`state`	string	No	At most 100 characters.
`lga`	string	No	Local government area. At most 100 characters.
`postalCode`	string	No	At most 20 characters.
`country`	string	Yes	ISO 3166-1 alpha-2.

Example request

bash

curl -X PATCH https://gp.useyona.com/i/v1/buyers/9f8e7d6c-5b4a-3210-fedc-ba9876543210 \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "legalName": "string"
  }'

Responses

The buyer after the edit.

Errors: 400, 401, 402, 403, 404, 409, 429, 503

Delete a buyer

DELETE /i/v1/buyers/{id}

buyer.delete. Deleted, or archived instead when an issued invoice names the buyer (outcome says which).

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes

Example request

bash

curl -X DELETE https://gp.useyona.com/i/v1/buyers/9f8e7d6c-5b4a-3210-fedc-ba9876543210 \
  -H "Authorization: Bearer sk_test_your_key_here"

Responses

What happened to the buyer.

Errors: 400, 401, 403, 404, 429

Delete several buyers

DELETE /i/v1/buyers/bulk

buyer.delete. Up to 100 distinct ids, each handled like a single delete: deleted, or archived when an issued invoice names the buyer. Ids that are not found are listed, not refused.

Who can call it: API key or signed-in user.

Request body

Field	Type	Required	Description
`ids`	array of string (uuid)	Yes	1 to 100 items.

Example request

bash

curl -X DELETE https://gp.useyona.com/i/v1/buyers/bulk \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "9f8e7d6c-5b4a-3210-fedc-ba9876543210"
    ]
  }'

Responses

Which ids were deleted, archived or not found.

Errors: 400, 401, 403, 429

Check whether a TIN is on the e-invoicing network

GET /i/v1/buyers/reachability

buyer.read; free. Whether the tax authority’s e-invoicing network reaches this TIN — the check a form runs while a buyer TIN is typed. Cached per mode and TIN. When the tax authority cannot be asked the answer is still 200: an earlier answer with stale: true, or unavailable: true.

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`taxId`	query	string	Yes	1 to 32 characters.

Example request

bash

curl "https://gp.useyona.com/i/v1/buyers/reachability?taxId=33875194-0001" \
  -H "Authorization: Bearer sk_test_your_key_here"

Responses

The lookup’s answer.

Errors: 400, 401, 403, 422, 429, 503

Ask the tax authority about a TIN now

POST /i/v1/buyers/reachability/check

buyer.read; charged per request (refunded when no answer could be had). The same question as the free reachability check, asked afresh rather than from the cache. When the tax authority cannot be asked the answer is 200 with unavailable: true.

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`Idempotency-Key`	header	string	No	8–128 characters of A–Z, a–z, 0–9, `_` or `-`. A retry with the same key is not charged twice.

Request body

Field	Type	Required	Description
`taxId`	string	Yes	1 to 32 characters.

Example request

bash

curl -X POST https://gp.useyona.com/i/v1/buyers/reachability/check \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "taxId": "33875194-0001"
  }'

Responses

The lookup’s answer.

Errors: 400, 401, 402, 403, 409, 422, 429, 503

Search buyers

GET /i/v1/buyers/search

buyer.read. Live buyers whose name, legal name or tax id matches q (at least 2 characters); at most limit (default 10, up to 20).

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`q`	query	string	Yes	2 to 100 characters.
`limit`	query	number	No	Default: `10`. Between 1 and 20.

Example request

bash

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

Responses

The matching buyers.

Errors: 400, 401, 403, 429

Get the buyer form options

GET /i/v1/buyers/setup

buyer.read. The party types, the tax-id types of the organisation’s jurisdiction, and the countries.

Who can call it: API key or signed-in user.

Example request

bash

curl https://gp.useyona.com/i/v1/buyers/setup \
  -H "Authorization: Bearer sk_test_your_key_here"

Responses

The option lists.

Errors: 401, 403, 429, 503

Get a buyer’s tax number verification status

GET /i/v1/buyers/{id}/verification-status

buyer.read. The latest verification and the buyer’s tax-id status.

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes

Example request

bash

curl https://gp.useyona.com/i/v1/buyers/9f8e7d6c-5b4a-3210-fedc-ba9876543210/verification-status \
  -H "Authorization: Bearer sk_test_your_key_here"

Responses

The latest verification.

Errors: 400, 401, 403, 404, 429

Verify a buyer’s tax number

POST /i/v1/buyers/{id}/verify-tax-number

buyer.verify_tax_id; a charge is held while the check runs. 202 when a new verification starts; 200 with the one already pending. Follow it with the verification status route.

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes

Example request

bash

curl -X POST https://gp.useyona.com/i/v1/buyers/9f8e7d6c-5b4a-3210-fedc-ba9876543210/verify-tax-number \
  -H "Authorization: Bearer sk_test_your_key_here"

Responses

A verification was already pending; this is it.

A new verification was started.

Errors: 400, 401, 402, 403, 404, 409, 422, 429, 503