curl --request POST \
--url https://breadbox.example.com/api/v1/counterparties \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"name": "<string>",
"website_url": "<string>",
"logo_url": "<string>",
"category_id": "<string>",
"mcc": "<string>"
}
'{
"id": "<string>",
"short_id": "<string>",
"name": "<string>",
"website_url": "<string>",
"logo_url": "<string>",
"category_id": "<string>",
"mcc": "<string>",
"canonical_counterparty_id": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}Create a counterparty
Requires full_access scope. Creates a counterparty by name with optional enrichment (website_url, logo_url, category_id, mcc). A duplicate live name is rejected — edit the existing one instead. To bind charges, use the assign endpoint or author an assign_counterparty rule.
curl --request POST \
--url https://breadbox.example.com/api/v1/counterparties \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"name": "<string>",
"website_url": "<string>",
"logo_url": "<string>",
"category_id": "<string>",
"mcc": "<string>"
}
'{
"id": "<string>",
"short_id": "<string>",
"name": "<string>",
"website_url": "<string>",
"logo_url": "<string>",
"category_id": "<string>",
"mcc": "<string>",
"canonical_counterparty_id": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}Authorizations
Breadbox API key with format bb_<base62>. Carries either read_only
or full_access scope. Write endpoints (and a handful of sensitive
reads — /api-keys, /users/{user_id}/login) require full_access;
endpoints that require it are flagged in their description.
Body
Response
Created counterparty.
The canonical, cross-provider "other side" of a charge (a merchant or non-merchant). Surrogate identity + name + optional enrichment; membership comes from assign_counterparty rules, not a normalizer.