Supplier API Tech Specs

 Download (YAML) OpenAPI specification

Credential Management

A Supplier User with API Admin permission will navigate to the API Management page in Magnit VMS to generate your supplier's credentials, which include a Client Key, Client Secret, and Credential Key. Credentials are valid for 180 days and upcoming expiration email notifications are sent. When replacement credentials are generated, if current credentials are still valid for more than a week, the existing ones will expire one week after the new ones are created. This allows for testing and validation of new credentials.

Verbs
Supported verbs are POST, GET and PATCH.

Error Response

• Error response uses "Content-Type" as "application/problem" and JSON format.
• 2XX status codes are used for successful request processing.
• 4XX HTTP status codes are used for client errors with a specific resource.
• 500 HTTP status code is used for server errors.

Unknown Attributes
Any unrecognized parameters or attributes in the request are disregarded during processing.

Rate Limiting
We currently apply an API rate limit of 60 requests per minute per IP address. If this limit is exceeded, the IP will be temporarily blocked for one minute.

Pagination

• Some endpoints are supported by pagination.
• Pagination is managed through “page” and “size” query string parameters, with the default value for page set to 1 and size set to 5,000. These parameters can be adjusted to retrieve a specific range of data.
• Please note that these parameters are case-sensitive and must be lowercase.
• Next Page: The response includes a “nextpage” value, which provides the URL for the next page of results.
• Page: The “page” parameter allows you to retrieve data from a specific page based on the page size.
• Size: The default value is 5,000 records per page, with a maximum limit of 20,000 records per page to ensure reasonable response times. If a request specifies a size greater than this limit, the maximum value will be applied instead.
• Total Records: The “totalrecords” field indicates the total number of records without pagination.
• Total Pages: The “totalpages: indicates the total number of pages based on the page size.
• Data Element: The “data” node contains the report records.
  
  

Sample Pagination URL: https://{baseurl}/endpoint/retrievePagedData
Sample Pagination URL with page and size parameters: https://{baseurl}/endpoint/retrievePagedData?page=2&size=2000

Make a POST call to the token endpoint {baseurl}/get-api-token.  The request body should be in JSON format.  The three components of your Supplier’s API keys located on the API Management page in the VMS should be passed in the body, and if successful, an access token will be returned.  

Sample Request:

{
    "CredentialKey": 1234,
    "ClientKey": "XXXX",
    "ClientSecret": "XXXX"
}

Once you have the access token you can call the other endpoints. Use it in the Authorization header as below:

Authorization: Bearer <token>

If further assistance is needed, please open a case at Magnit Global Services & Support Center.