For AI agents: a documentation index is available at https://docs.coverbase.com/llms.txt. This page is also available in markdown by appending .md to the URL.
A vendor’s supplier profile is what your organization holds about how to pay and reach that supplier: its bank accounts, its sites (addresses and other locations), its tax and company registrations, its diversity records, and the legal entities of yours it is assigned to. In the dashboard these are the records on the vendor’s Know-Your-Vendor tab; see Supplier information. This API is how a finance system or middleware reads those records, writes them, and keeps up with changes to them.
The profile is not an object with an ID of its own. Every record in it belongs to a vendor (cbvndr_...) and lives under /v1/vendors/{vendor_id}/. The one exception is the list of your own legal entities, at /v1/legal_entities.
Know Your Vendor is not on for every organization. While it is off, every endpoint on this page returns
404 with the code not_enabled. If you get that response, ask your Coverbase account team to turn it on.Idempotency-Key. A tax registration write is an upsert and safe to repeat; the other writes are not, so list the records before you retry one that timed out.
No endpoint needs a scope: a standard integration key can call all of them. The scopes in the last column change what a call returns or does; see masking and scopes.
How the profile fits together
What a profile holds
Two more IDs appear in responses: a legal entity (
cble_...) is one of your own contracting entities, set up under Configuration → Legal entities, and a bank change review (cbbarev_...) is a bank write waiting for a reviewer.
Sites are also the vendor’s locations: the sites you read and write here are the ones on the vendor’s Locations card and on the Risk geography map.
Who changes what
Changes to these records, whoever makes them, are appended to the vendor’s change history. The same history drives the Know-Your-Vendor tab, the supplier profile webhooks and the change feed. A change made with an API key is recorded with
actor_type api and actor_label API, and the records it creates carry source api.
What waits for approval
Both settings are in Configuration → Know Your Vendor Settings; see Configuring it for your organization. A reviewer decides a queued bank change on the vendor’s Know-Your-Vendor tab or on the Vendor changes page. The API has no call to approve or reject one. Retiring a bank account never waits.
Masking and scopes
An API key authenticates as a service account. With a standard key, an account number, IBAN or tax identifier comes back as its last four characters (****6789), a bank account’s other fields are not returned apart from its SWIFT/BIC, and every bank write queues for review. An admin can grant a key two scopes that change this, under Admin scopes (optional) on the API keys page:
Grant either only to a key that needs it. See API key scopes and role-based masking. A dashboard session token also works on these endpoints, but it never unmasks values and never skips review.
Country rules and validation
Bank accounts, sites and tax registrations are checked against the rules for their country, which Supplier countries lists field by field. Values are normalized first, and the normalized value is what Coverbase stores: spaces come out of an IBAN, and a United Kingdom sort code shorter than six digits is padded with leading zeros.- An error rejects the write with
422and the codevalidation_failed, and nothing is saved. - A warning lets the write through. The warning is kept on the record’s
validation_results.
config_version reads unconfigured.
Every record that was validated carries the outcome in validation_results:
A write that fails validation returns the same results in the error body. It uses an
error key rather than the usual code:
Errors every endpoint can return
Authentication failures and the IP allowlist behave as on every public endpoint; see API conventions. Calls made with an
ak_ key are recorded in the public API audit log.
Bank accounts
The bank account object
Two-letter country code of the bank that holds the account.
null on an account recorded before country validation existed.A label for the account, such as
Operating account. It is not the account holder’s name.passed, passed_with_warnings, or not_validated for an account recorded before country validation existed.The validation outcome.
domestic or wire, derived when the account was saved. It is wire when the bank’s country is not one your assigned legal entities pay from, and null when the vendor had no active legal entity assignment with a country at the time.Every field of the account in full, keyed by field key. A field the account does not use is an empty string. Present only on list bank accounts for a key with
banking:read; null everywhere else.List bank accounts
Returns the vendor’s active bank accounts as a plain array, primary first, then oldest first. Retired accounts and changes still waiting for review are not included. The list is not paginated. Auth: anyak_ key. With banking:read, each account also carries values.
Path parameters
Example request
cURL
Example response
200 OK, for a key with banking:read. Without the scope, values is null.
Add a bank account
Validates the account against its country’s rules, then either queues it for a reviewer or saves it. Auth: anyak_ key. A key with review:sensitive_changes skips the review queue.
Path parameters
Request body
Two-letter country code of the bank that holds the account, which is not always the supplier’s own country. It decides which fields are asked for and which rules apply.
The account’s fields, keyed by field key, for example
{"branch_code": "076401251", "account_number": "000123456789", "account_type": "checking"}. Keys the country does not define are dropped. Values can be null.Three-letter currency code.
BRL is refused when the supplier’s own address is outside Brazil, judged by its primary site (or its first site, if none is primary). A supplier with no sites is not checked.A label for the account. On a write that is queued for review, it takes effect when the change is approved.
true makes this the vendor’s primary account and demotes the current one. Omit it or send false for a secondary account.A document already uploaded for this vendor with the Documents API (
cbvdoc_...), such as a bank statement showing the account belongs to the supplier. A document of another vendor is refused with 422 and the code invalid_document. On a write that is queued for review, it is attached when the change is approved.Example request
cURL
Example responses
202 Accepted: the account is queued for review. This is the default outcome.
submitted event whose entity_id is the review_id. See following a queued bank change.
201 Created: the account is saved, because your organization has turned off Bank changes need a reviewer or the key carries review:sensitive_changes. The body is the bank account object, with values always null. The VendorBankAccount.Created webhook fires.
Error responses
Update a bank account
Replaces an account’s details. It takes the same body as add a bank account, andbank_country and values are required. values replaces the whole set, so send every field the account should keep, not only the one that changed.
Auth: any ak_ key. A key with review:sensitive_changes skips the review queue.
The outcomes match the add call: 202 Accepted with a review_id while the change waits for a reviewer, or 200 OK with the updated bank account object when it is applied at once. The live account keeps serving its current details until a reviewer approves.
A PATCH whose
values match what the account already holds is not a bank change. Its currency, bank_account_name, is_primary and statement_document_id are applied at once, without review, and when one of them changes, the change feed records an updated event and VendorBankAccount.Updated fires. Sending back exactly what is stored records nothing. Any difference in values, including a new swift_bic, bank_name or account_type on the same account number, is a bank change and waits for review like any other.Path parameters
Example request
cURL
Error responses
Retire a bank account
Retires an account at once; retiring never waits for review. The account stops being primary, drops out of list bank accounts, and theVendorBankAccount.Retired webhook fires. The call takes no body and returns 200 OK with the bank account object, status set to retired. Calling it again on a retired account returns the account unchanged and records nothing, so a retry is safe.
Auth: any ak_ key.
Path parameters
Example request
cURL
Error responses
Following a queued bank change
The review ID is the only handle a queued change has, and the API has no endpoint that reads a review. Follow it through the change feed:- A
rejectedevent onbank_accountwhoseentity_idis yourreview_idmeans the reviewer turned it down, and itssnapshotcarries therejection_reason. The live account never changed. - An
approvedevent onbank_accountmeans it went live. Itsentity_idis the bank account ID, not the review ID: for a change to an existing account it is the account you patched, and for a new account it is the account the approval created, which then appears in list bank accounts. Nothing in the event names the review, so match a new account to your request by vendor,bank_countryandaccount_number_masked.
Sites
A site is one place the supplier operates, at whatever precision is known: a full street address, a city, or a country on its own. Only the country is required. Sites carry the addresses your finance system pays and orders against, and they are the vendor’s locations on the Risk geography map.The site object
The service this location belongs to, when someone scoped it to one on the vendor page. The API does not set it.
ordering, billing, service_delivery, hq or other. A label set on the vendor page; nothing derives it.What the address is for in your finance system:
primary or remittance. An address is a registration address by carrying a tax registration, not by its purpose.Derived from the address unless the API sets it: the country code, or the country and subdivision (
US-NY) in the United States, Canada, India and Brazil. The supplier is never asked for it.The language purchase orders for this address are sent in, as a lowercase ISO 639-1 code.
Filled in by Coverbase after the site is saved, from the address.
null until then, and always null for a country-only site.Your finance system’s id for this address, such as its Oracle supplier address id. Set only through the API and never shown in Coverbase.
Unix timestamp (seconds) when the address was made inactive. An inactive address stays on file and in the list;
null while it is in use.The validation outcome. Postal-code format problems, over-long address lines and a missing PO email address are warnings, never errors.
List sites
Returns the vendor’s sites as a plain array, primary first, then oldest first. The list is not paginated. Auth: anyak_ key.
Path parameters
Example request
cURL
Example response
200 OK:
Add a site
Adds a site and returns201 Created with the site object. The SupplierSite.Created webhook fires.
Auth: any ak_ key.
Path parameters
Request body
Up to 120 characters. Send the ISO 3166-2 subdivision code (
NY or US-NY) where you have it: in the United States, Canada, India and Brazil the tax region is built from it, and a name such as New York gives the country-level region.Up to 60 characters. Your finance system’s own tax region for this address. Omit it and Coverbase derives one from the address.
Up to 20 addresses where purchase orders for this address are emailed. A malformed address is refused with
422. A primary site with an address line and no PO email saves with an email.missing warning, except in China, where no PO email is asked for.Up to 20 addresses where remittance advice for this address is emailed. A site whose
address_purpose is remittance and has none saves with an email.missing warning.The language purchase orders for this address are sent in, as an ISO 639-1 code:
ar, zh, hr, cs, da, nl, en, fi, fr, de, el, he, hu, id, it, ja, ko, ms, no, pl, pt, ro, ru, sk, sl, es, sv, th, tr, uk, vi. Case is ignored. Any other value is refused with 422 and a field.enum result on po_language.Up to 120 characters. Your finance system’s id for this address. On an update, omitting it keeps the stored id and an empty string clears it.
true makes the address inactive and false makes it active again. Omit it to leave the address as it is. The primary address cannot be made inactive.Example request
cURL
latitude and longitude still null.
Error responses
Update a site
Takes the same body as add a site and returns200 OK with the updated site object. The SupplierSite.Updated webhook fires.
Auth: any ak_ key.
Treat it as a replacement of the address rather than a partial update:
country_codeis required.- Omitting an address line,
city,state_province,county,postal_code,location_code,csp_remit_to_idordescriptionclears it. Send every value you want to keep. - Omitting
site_name,site_contextoraddress_purposekeeps the stored value. An emptysite_nameclears it; the other two cannot be cleared here. - Omitting
po_emailsorremittance_emailskeeps the stored list. Send[]to clear one. - Omitting
po_languagekeeps the stored language. Send""ornullto clear it. - Omitting
tax_regionderives it from the address again. is_primary: truemakes the site primary.falsedoes not demote it; mark another site primary instead.- Changing the address (other than
address_line2) clearslatitudeandlongitudeuntil Coverbase places the new one.
Path parameters
Example request
cURL
Error responses
Delete a site
Removes the site and returns204 No Content. It no longer appears in list sites, on the vendor’s Locations card or on the map. The change history keeps the record of it, and the SupplierSite.Deleted webhook fires.
Auth: any ak_ key.
Path parameters
Example request
cURL
Error responses
Tax registrations
A tax registration is one tax or company identifier the supplier holds in one country, such as a US EIN or a UK VAT number, or a declared exemption in place of one. A registration can belong to the supplier as a whole or to one of its sites. After a registration is saved, Coverbase checks it against the public register for that country where one exists, in the background. The check never blocks a write; it updatesregistry_status when it completes.
The tax registration object
How far verification got:
format, checksum (its check digits are valid) or registry (the public register confirmed it). The schema also defines document, which nothing sets.pending, verified, not_found or unavailable. unavailable means the register could not be reached and says nothing about the supplier. null when the country has no register Coverbase checks.The country’s registration details beside the number, keyed by field. Colombia’s are
nature, legal_entity_type, document_type, dv and ciiu, alongside its other details; Brazil’s are its state and municipal registrations. An empty object for a country without any. The keys and options are on each country’s page under Supplier countries.The validation outcome.
The identifier in full. Present only on list tax registrations for a key with
banking:read; null everywhere else.List tax registrations
Returns the vendor’s tax registrations as a plain array, ordered by country and then by type. The list is not paginated. Auth: anyak_ key. With banking:read, each registration also carries value.
Path parameters
Example request
cURL
Example response
200 OK, for a key without banking:read:
Add or update a tax registration
Saves a registration and returns201 Created with the tax registration object, whether it created a registration or updated one. A vendor holds one registration per country and type, and separately one per site, country and type: posting the same country_code and tax_id_type again (with the same site_id, or none) updates that registration. A new number restarts the register check. The SupplierTaxRegistration.Updated webhook fires in both cases.
Auth: any ak_ key.
Path parameters
Request body
The tax ID type key for that country, such as
ein, vat or tax_id. Keys are case-sensitive. A key the country does not define is stored without any format or checksum check, so check the spelling.The identifier, 1 to 64 characters. Required unless
is_exempt is true, and refused when it is.One of this vendor’s active sites (
cbsite_...), for a registration held at that address. Omit it for the supplier’s own registration.true records that the supplier is exempt from this registration instead of giving a number.A document already uploaded for this vendor with the Documents API (
cbvdoc_...), such as the registration certificate. A document of another vendor is refused with 422 and the code invalid_document. Omitting it on an update keeps the one already attached. In Argentina, Brazil, Chile, Colombia, Costa Rica, the Dominican Republic, Ecuador, Guatemala, Mexico, Panama, Paraguay, Peru and Uruguay, a registration without a certificate saves with a tax_certificate.expected warning.The country’s registration details, as an object of field key to string value. Validated against the country’s rules: in Colombia
dv must be the NIT’s verification digit, and nature (J or N), legal_entity_type (foreign_entity, individual or legal) and document_type (13, 31 or 43) are required. Omitting details keeps the stored details, and the country’s required details are still checked against them, so a new Colombian registration needs them. A Colombian NIT is sent without its verification digit, which goes in dv.Example request
cURL
123456789.
Error responses
Diversity records
A diversity record is the supplier’s declaration for one inclusion category, optionally backed by a certificate. Suppliers submit them through a questionnaire or the portal, and your staff can enter them on the Know-Your-Vendor tab. The API reads them but does not write them.List diversity records
Returns the vendor’s diversity records as a plain array, ordered by category. The list is not paginated. Auth: anyak_ key.
Path parameters
Example request
cURL
Example response
200 OK:
Diversity record object
minority_owned, women_owned, veteran_owned, service_disabled_veteran_owned, disability_owned, lgbtq_owned, small_business, small_disadvantaged_business, hubzone, historically_black_college, indigenous_owned, aboriginal_owned, other, or none_declared. none_declared is the supplier stating it holds none of the others, which is a different answer from never having been asked.Legal entities and assignments
Your legal entities are your own contracting entities, maintained under Configuration → Legal entities. An assignment says a supplier trades with one of them. The entity’sentity_code is what your finance system matches on, and its country decides whether a payment to a supplier’s bank account is domestic or wire.
List your legal entities
Returns your organization’s active legal entities as a plain array, ordered by name. Deactivated entities are left out. The list is not paginated. Auth: anyak_ key.
Query parameters
Example request
cURL
Example response
200 OK:
List a vendor’s legal entity assignments
Returns every assignment for the vendor, newest first, including requested and rejected ones. The list is not paginated. Auth: anyak_ key.
Path parameters
Example request
cURL
Example response
200 OK:
Legal entity assignment object
The user who requested it (
cbuser_...). For an assignment made through the API, this is your organization’s API service account.Assign legal entities
Assigns the vendor to one or more of your legal entities and returns201 Created with an array of the new assignments. The call is all or nothing: if any entity in the batch is already assigned, nothing is created.
Each assignment is active at once, and fires the SupplierLegalEntityAssignment.Assigned webhook with the entity code, unless Legal entity assignments need approval is on. Then it is requested until someone decides it in the dashboard. An active assignment’s country feeds the payment method of bank accounts saved after it; an account already on file keeps its method until it is next saved.
Auth: any ak_ key.
Path parameters
Request body
One to five legal entity IDs (
cble_...) from list your legal entities. Each must be one of your active legal entities: an ID that is not, including a deactivated entity, fails the whole call and nothing is created.The age in days, 0 to 3650, of the purchase requisition behind the request. Above 30 days, a
justification is required. Omit it when no requisition is quoted.Example request
cURL
Error responses
Contacts
A vendor’s contacts are the people on its record. These two endpoints let your finance system store its own id for each contact, such as its Oracle supplier contact id, so a sync updates the contact it already holds. The id is never shown in Coverbase, and it is kept when someone edits the contact list in the dashboard, as long as the contact keeps the same email address.List contacts
Returns the vendor’s contacts as a plain array, each withname, title, email, phone_number and external_id (null until one is set).
Auth: any ak_ key.
Set a contact’s finance system id
Finds the contact by email address, ignoring case, stores the id on it, and returns the contact. Auth: anyak_ key.
Request body
Example request
cURL
Error responses
Update requests
An update request asks a supplier to review and update named sections of their profile. Coverbase sends the supplier no email: the request opens those sections on the Profile page of the centralized supplier portal, where each is marked as one you asked about. It therefore reaches only a supplier who has a portal, in an organization that has turned the Profile section on. The sections stay open until the request expires, alongside any sections your organization leaves open all the time. While a request is open, Coverbase reminds the vendor’s relationship owners (or, if it has none, its risk analysts) 3 and 7 days after it was sent. When its expiry date passes, the request becomesexpired.
The update request object
The sections the request covers. See send an update request for the values.
sent while open, draft if created with send: false, and expired once past expires_at. The schema also lists in_progress, submitted, reviewed and closed; no current workflow moves a request into those.true for a request your team created inside Coverbase, such as adding legal entities to a supplier. An internal request is never sent to the supplier and completes once your team has decided what it covers. false for every request sent to a supplier, including all requests created through the API.List update requests
Returns the vendor’s update requests as a plain array, newest first, including internal requests (flagged withis_internal). The list is not paginated.
Auth: any ak_ key.
Path parameters
Example request
cURL
Send an update request
Creates a request and, unlesssend is false, sends it. Returns 201 Created with the update request object. The dashboard has no button for this; the API is the only way to send one.
Auth: any ak_ key.
Path parameters
Request body
The sections to open, from the values in the table below. Omit it or send
[] to use Sections to request by default from Know Your Vendor Settings, which is po_email, addresses and bank_accounts unless your organization changed it.The supplier contact the request is for. Stored and returned as
recipient_email; Coverbase does not email it.false saves the request as a draft, which opens nothing. No endpoint sends a draft later.Example request
cURL
The change feed
Changes to your vendors’ supplier profiles are appended to one org-wide history of change events (cbpce_...), and nothing edits or deletes an event once written. The feed returns that history oldest first. Use it to reconcile after missed webhooks, or poll it instead of receiving webhooks at all.
The change event object
Change event ID (
cbpce_...). Webhooks for the same change carry it as change_event_id, so use it to deduplicate across the two.What changed:
bank_account, site, tax_registration, diversity_record or legal_entity_assignment.The ID of the record that changed. For a queued or rejected bank change, it is the review ID (
cbbarev_...).created, updated, deleted, retired, submitted, approved, rejected or revealed. See what the feed records.Who made the change, for display:
API, Supplier portal (a questionnaire answer), a portal user’s email address, a staff member’s name, or null.The fields that changed, each as
{ "old_value", "new_value" }. Account and tax numbers appear only as their last four characters.The record as saved after the change, masked the same way. A legal entity assignment’s snapshot includes the entity’s
entity_code and the site.What the feed records
The feed is the audit trail, so it holds more than the webhooks send. Filter onaction before you apply anything to your finance system.
List changes
Returns one page of change events across all vendors, oldest first. Auth: anyak_ key.
Query parameters
Unix timestamp (seconds). Returns events at or after this time. Omit it to start from the first event.
Only these
entity_type values, from the five above. Repeat the parameter for more than one: types=bank_account&types=site. Any other value is rejected with 422.The
next_cursor from the previous page. Treat it as opaque. A cursor Coverbase cannot read is ignored, and the feed starts again from since, or from the first event without one.Example request
cURL
Example response
200 OK:
The page of change events, oldest first.
Keeping up with the feed
Page withcursor until has_more is false. The last page carries no cursor, so remember the created_at of the last event you applied and pass it as since on your next poll. Events from that same second come back again, so skip any id you have already applied.
Field keys
The API names each field by a key, while the dashboard and the supplier’s form show a label that differs by country. These keys come from the rules Coverbase ships for each country. If Coverbase has overridden a country’s rules for your organization, ask your account team which keys changed.Bank account values
Every country uses the same keys for the common fields, whatever the form calls them:
Every country also takes an optional intermediary bank:
intermediary_country, intermediary_city, intermediary_account_number, intermediary_bank_name, intermediary_branch_code, intermediary_iban and intermediary_swift_bic. When any of them is sent, intermediary_country and intermediary_account_number are required.
Eight countries add their own:
Which keys a country requires is on its page under Supplier countries.
Tax ID types
Sixty-nine countries use a single key,tax_id, for their tax or VAT number. The other forty use the keys below.
Tax ID type keys by country
Tax ID type keys by country