Birlesa is a B2B platform: company pages built from official records, buyers' needs matched to suppliers, quotes, deals, and payments held in escrow. These pages explain how your software works with it.
| You want to | Use |
|---|---|
| Read public data: companies, opportunities, the monthly index, export requirements | The REST API, without a key or with one for a higher budget |
| Act for your organization: post needs, ask suppliers for quotes | The REST API or the MCP server, with an API key that has the permission |
| Hear when something happens to your organization | Webhooks |
| Read the records a webhook names (needs, deals, quotes, escrows, shipments) | /v1/org/... with an org:read key |
| Give an AI agent Birlesa's tools | The MCP server at /mcp |
| Use aggregated market data under contract (banks, unions, public bodies) | Data products |
Base URL and formats
- Production:
https://api.birlesa.com. Sandbox access is not offered yet (sandbox). - Requests and responses are JSON (UTF-8). Times are RFC 3339 in UTC. Money amounts are decimal strings (
"1250.00"), never floats. Countries are ISO 3166-1 alpha-2 (TR,SA);EUandGCCname blocs where a field says so. - The full contract is the OpenAPI document, at birlesa.com/openapi.json(opens in a new tab). Every operation, field and error code is listed there.
Pages
- Authentication: API keys, OAuth client credentials, permissions.
- Limits and quotas: rate limits, daily quotas, usage.
- Errors: the problem format and the codes you will meet.
- Webhooks: endpoints, signatures, retries. The event catalog lists every event.
- Versioning and deprecation: what may change in
/v1, and how removals are announced. - MCP server: tools for AI agents.
- Sandbox: build against fake partners and test data (not offered yet).
- Service levels: what we aim for, and how we tell you when we miss it.
- Data products: aggregated datasets under contract.
Ground rules
- Keep secrets (API keys, client secrets, webhook secrets) on your servers. They are shown once; we keep only a hash or a sealed copy and cannot show them again. If one leaks, revoke it and issue a new one.
- Personal data stays out of the API by design. Webhooks carry ids, not texts or names. Conversation messages are read by people in the panel, not through keys.
- Everything an integration does is recorded against its key or client in your organization's audit trail.