The Convictional API provides supplier enablement functionality to buyers and suppilers to trade with each other via API. Here you will find our complete API reference, along with guides and examples to follow. You can also test out each endpoint within this site, you just need to provide your API key.

Subscribe to Breaking Changes

Before you go on, subscribe to our Breaking Change notifications. Any time we plan a breaking change, we'll send you advance notice with instructions on how to upgrade.

Get Your API Key

Each registered user of Convictional has access to an API key. Provide this API key in the Authorization header to authenticate yourself to our services. To get your API key, visit your Settings page.

Example: Authorization: 18682ba6-3c6e-4d98-9d34-6e142bea4695

Buyer and Seller APIs

Companies on the platform are either buyers or sellers:

  • Seller accounts can access the Seller and Shared API endpoints.
  • Buyer accounts can access the Buyer and Shared API endpoints.

You can see what kind of account you have in your Settings page.

Request IDs for Support

In each response, we will include an X-Request-ID header with a value. This value is used by our support team to track the lifecycle of your request through our API. If you ever need support, we will ask for this value for the affected requests. It's best practice to log this value on each response in case you need it in the future.

Example: X-Request-ID: 6e142bea4695-18682ba6-9d34-3c6e-4d98

Client Libraries

Convictional doesn't currently have any supported client libraries. We are planning to add them in the future. Until then, you can generate client libraries for each API (Shared, Seller and Buyer respectively) using the following OpenAPI definitions for your preferred language using any OpenAPI library generator:

Rate Limiting

For API requests using authentication via API key, you can make up to 5 requests per second. Rate limiting is bucketed in 1 second intervals and shared across all endpoints for a given API key. Requests that exceed the limit will return a 429 HTTP response status and otherwise will have no have no impact on application state.

You can make use of the following response headers within your client:

  • X-Rate-Limit-Limit: the maximum number of requests per bucket. Currently 5.
  • X-Rate-Limit-Duration: the duration of a bucket in seconds. Currently 1.

Versioning

We do not maintain multiple versions of our APIs. This means that when breaking changes occur, we require all impacted clients to upgrade. Your willingness to work with us by staying up-to-date allows us to build better products and incorporate your feedback faster. In turn, we work hard to make each upgrade as predictable and simple as possible. We notify you at least 6-12 weeks in advance of every upgrade and provide step-by-step guides to minimize the effort required by your team. In order to be notified, you must subscribe to our Breaking Change notifications.