The Convictional API provides supplier enablement functionality to buyers and suppliers 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 Change Announcements
Before you go on, make sure to subscribe to Breaking Change announcements to stay in the loop! We announce breaking changes to impacted API clients as well as all subscribers to this list.
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.