McMaster-Carr Product Information API

Introduction

The McMaster-Carr Product Information API provides an external method for programmatically retrieving our publicly available product information. Using this service, approved customers can import data on our product offering into their own systems and stay up to date as specifications change. This API uses REST principles and the authorization scheme, requests, responses, and error codes described below.

You can view sample requests by downloading our Postman collection JSON and importing it into Postman. After integrating with our system, you can test responses using the imported collection.

Please reach out to us at eCommerce@mcmaster.com if you have any questions or would like to begin the integration process.

Authorization

Certificates

McMaster-Carr provides a client certificate and an accompanying password for each approved customer. The client certificate must be attached to each request.

Authentication

To use the API, users must start by making a Log In request. If the client certificate, username, and password are all correct and authorized, the API will respond with an authorization token and the time that it will expire. This authorization token must be included as a bearer token on all subsequent requests. For example,

Authorization: Bearer anZXMWd403820879912OWCtRaWsyaFFXTURVeWhRRHZ6QTJSZw==

Multiple authorization tokens can be valid at the same time for each user. A token expires when it is used in a Log Out request or automatically after 24 hours.

Limits on data retrieval

To get data on a certain product, you must subscribe to information on it through an Add Product request. In order to protect our data, each user has limits on how many product subscriptions they can maintain in total as well as how many can be added each day.

In order to ensure that all users are able to get the information that they need, bandwidth-intensive endpoints, such as retrieving CAD files, are rate-limited.

Errors

When a server error occurs, we will send a response body in the following format:

{
    "ErrorCode": 500,
    "ErrorMessage": "INTERNAL_SERVER_ERROR",
    "ErrorDescription": "An internal server error occurred."
}

The status code of the response will match the ErrorCode property and depend on the error. The ErrorMessage is the category of error. The ErrorDescription property describes the error in more detail, sometimes including scenario-specific information related to your account or part number. The errors specific to each request can be found in Requests, but common errors across different requests are listed below. Note that INTERNAL_SERVER_ERROR responses mean there was an unexpected error on our end. Please reach out to us for further investigation.

Code Message Description
400 BAD_REQUEST Improperly formed request. Please check your POST body for errors.
400 BAD_REQUEST Invalid part number: {{PARTNUMBER}}
400 BAD_REQUEST Invalid file path requested
400 BAD_REQUEST Invalid file type requested
403 EXPIRED_AUTHORIZATION_TOKEN Invalid authorization token: {{authToken}}. Please log in again to create a new one.
403 NOT_SUBSCRIBED_TO_PRODUCT You are not subscribed to this product: {{partNumber}}
500 INTERNAL_SERVER_ERROR An internal server error occurred.

Requests

Overview

This table summarizes all of the requests that can be made to the McMaster-Carr Product Information API

Name Http Method Uri Stem Description
Log in POST /v1/login This request logs in users with valid credentials and certificates to return an authorization token.
Log out POST /v1/logout Log out the user by expiring the authorization token
Add product PUT /v1/products Adds a product to the user's list of subscribed products and returns the information for the product
Remove product DELETE /v1/products Removes a product from a user's list of subscribed products
Changes GET /v1/changes Retrieves all of the part numbers on a user's subscribed products list that have changed since a given start date.
Product information GET /v1/products/* Retrieves product information for a given part number
Price GET /v1/products/*/price Retrieves the current price of a certain product
Image GET /v1/images/* Retrieves an image from a relative path
CAD GET /v1/cad/* Retrieves a CAD file from a relative path
Datasheet GET /v1/datasheets/* Retrieves a datasheet from a relative path

Details

Log in

Request This request logs in users with valid credentials and certificates to return an authorization token.
Url https://api.mcmaster.com/v1/login
Method POST
Request Body {
    "UserName":"{{username}}",
    "Password":"{{password}}"
}
Success Responses Example {
    "AuthToken": "VXVPTHM746877516169vUkVXTFdvYTV0U1I2VTZidnNYVzc3OCtBPT0=",
    "ExpirationTS": "2019-07-23T22:08:50.6227667Z"
}
Codes 200 OK
Error Responses Example {
    "ErrorCode": 401,
    "ErrorMessage": "LOGIN_FAILED",
    "ErrorDescription": "Login failed."
}
Codes 400 Bad Request, Improperly formed request. Please check your POST body for errors.
401 Unauthorized, Login failed.
401 Unauthorized, Too many failed login attempts.
401 Unauthorized, Incorrect username or password.
401 Unauthorized, This account ID is not authorized for the API: {{account ID}}

Log out

Request Log out the user by expiring the authorization token
Url https://api.mcmaster.com/v1/logout
Method POST
Request Body N/A
Success Responses Example Empty response body
Codes 204 No Content
Error Responses Example {
    "ErrorCode": 500,
    "ErrorMessage": "INTERNAL_SERVER_ERROR",
    "ErrorDescription": "An internal server error occurred."
}
Codes 403 Forbidden, Invalid authorization token: {{authToken}}. Please log in again to create a new one.

Add product

Request Adds a product to the user's list of subscribed products and returns the information for the product
Url https://api.mcmaster.com/v1/products
Method PUT
Request Body {"URL":"https://mcmaster.com/{{partNumber}}"}
Success Responses Example {
    "PartNumber": "4936K451",
    "ProductStatus": "Active",
    "FamilyDescription": "Compact Extreme-Pressure Steel Pipe Fitting",
    "DetailDescription": "Adapter, 1/2 NPT Female, M20 x 1.5mm Male Thread",
    "Specifications": [
        {
            "Attribute": "Shape",
            "Values": [
                "Straight"
            ]
        },
        ...
        {
            "Attribute": "For Use With",
            "Values": [
                "Water",
                "Air",
                "Hydraulic Fluid",
                "Oil"
            ]
        }
    ],
    "Links": [
        {
            "Key": "Price",
            "Value": "/v1/products/4936K451/price"
        },
        {
            "Key": "Image",
            "Value": "/v1/images/contents/gfx/imagecache/493/4936k451p1-c01d-digitall@1x_636616342399401664.png"
        },
        {
            "Key": "2-D DWG",
            "Value": "/v1/cad/library/20180924/4936K451_COMPACT%20EXTREME-PRESSURE%20STEEL%20PIPE%20FITTING.DWG"
        },
        ...
        {
            "Key": "3-D STEP",
            "Value": "/v1/cad/library/20180924/4936K451_COMPACT%20EXTREME-PRESSURE%20STEEL%20PIPE%20FITTING.STEP"
        }
    ]
}
Codes 200 OK
201 Created
Error Responses Example {
    "ErrorCode": 403,
    "ErrorMessage": "EXPIRED_AUTHORIZATION_TOKEN",
    "ErrorDescription": "Invalid authorization token: {{authToken}}. Please log in again to create a new one."
}
Codes 400 Bad Request, Invalid part number: {{PARTNUMBER}}
403 Forbidden, Invalid authorization token: {{authToken}}. Please log in again to create a new one.

Remove product

Request Removes a product from a user's list of subscribed products
Url https://api.mcmaster.com/v1/products
Method DELETE
Request Body {"URL":"https://mcmaster.com/{{partNumber}}"}
Success Responses Example Empty response body
Codes 204 No Content
404 Not Found, Not subscribed to part number: {{partNumber}}. No subscription to remove
Error Responses Example {
    "ErrorCode": 400,
    "ErrorMessage": "BAD_REQUEST",
    "ErrorDescription": "Improperly formed request. Please check your POST body for errors."
}
Codes 400 Bad Request, Improperly formed request. Please check your POST body for errors.
400 Bad Request, Invalid part number: {{PARTNUMBER}}
403 Forbidden, Invalid authorization token: {{authToken}}. Please log in again to create a new one.

Changes

Request Retrieves all of the part numbers on a user's subscribed products list that have changed since a given start date.

Start date should be in the format MM/dd/yyyy. You can also include time: MM/dd/yyyy HH:mm.

Our systems will record the last set of changes and return only products that have changed since the given start date.

Note that changes means changes in the product information returned. Therefore, since the price link (unlike the other kinds of links) is stable, this end point will not reflect changes in price.
Url https://api.mcmaster.com/v1/changes?start={{startDate}}
Method GET
Request Body N/A
Success Responses Example {
    "PartNumbers": [
        "91292A834"
    ]
}
Codes 200 OK
Error Responses Example {
    "ErrorCode": 403,
    "ErrorMessage": "EXPIRED_AUTHORIZATION_TOKEN",
    "ErrorDescription": "Invalid authorization token: {{authToken}}. Please log in again to create a new one."
}
Codes 400 Bad Request, Improperly formed request. Please check your URL Query String for errors.
403 Forbidden, Invalid authorization token: {{authToken}}. Please log in again to create a new one.

Product information

Request Retrieves product information for a given part number

Discontinued products will be marked inactive and contain a link to a suggested replacement, if there is one. Any differences between the originally requested and suggested replacement parts will be listed as SuggestedProductDifferences.
Url https://api.mcmaster.com/v1/products/{{partNumber}}
Method GET
Request Body N/A
Success Responses Example {
    "PartNumber": "4936K451",
    "ProductStatus": "Active",
    "FamilyDescription": "Compact Extreme-Pressure Steel Pipe Fitting",
    "DetailDescription": "Adapter, 1/2 NPT Female, M20 x 1.5mm Male Thread",
    "Specifications": [
        {
            "Attribute": "Shape",
            "Values": [
                "Straight"
            ]
        },
        ...
        {
            "Attribute": "For Use With",
            "Values": [
                "Water",
                "Air",
                "Hydraulic Fluid",
                "Oil"
            ]
        }
    ],
    "Links": [
        {
            "Key": "Price",
            "Value": "/v1/products/4936K451/price"
        },
        {
            "Key": "Image",
            "Value": "/v1/images/contents/gfx/imagecache/493/4936k451p1-c01d-digitall@1x_636616342399401664.png"
        },
        {
            "Key": "2-D DWG",
            "Value": "/v1/cad/library/20180924/4936K451_COMPACT%20EXTREME-PRESSURE%20STEEL%20PIPE%20FITTING.DWG"
        },
        ...
        {
            "Key": "3-D STEP",
            "Value": "/v1/cad/library/20180924/4936K451_COMPACT%20EXTREME-PRESSURE%20STEEL%20PIPE%20FITTING.STEP"
        }
    ]
}
Codes 200 OK
Example (Discontinued) {
    "PartNumber": "1149A81",
    "ProductStatus": "Discontinued",
    "Links": [
        {
            "Key": "SuggestedProduct",
            "Value": "https://www.mcmaster.com/15185A41"
        }
    ],
    "SuggestedProductDifferences": [
        {
            "Attribute": "Material",
            "DiscontinuedProductValue": "Plastic",
            "SuggestedProductValue": "Stainless Steel"
        },
        {
            "Attribute": "Width",
            "DiscontinuedProductValue": "1-3/4\"",
            "SuggestedProductValue": "2\""
        }
    ]
}
Codes 200 OK
Error Responses Example {
    "ErrorCode": 403,
    "ErrorMessage": "EXPIRED_AUTHORIZATION_TOKEN",
    "ErrorDescription": "Invalid authorization token: {{authToken}}. Please log in again to create a new one."
}
Codes 403 Forbidden, Invalid authorization token: {{authToken}}. Please log in again to create a new one.
403 Forbidden, You are not subscribed to this product: {{partNumber}}

Price

Request Retrieves the current price of a certain product
Url https://api.mcmaster.com/v1/products/{{partNumber}}/price
Method GET
Request Body N/A
Success Responses Example [
    {
        "Amount": 3.46,
        "MinimumQuantity": 1,
        "UnitOfMeasure": "Each"
    }
]
Codes 200 OK
Error Responses Example {
    "ErrorCode": 403,
    "ErrorMessage": "EXPIRED_AUTHORIZATION_TOKEN",
    "ErrorDescription": "Invalid authorization token: {{authToken}}. Please log in again to create a new one."
}
Codes 403 Forbidden, Invalid authorization token: {{authToken}}. Please log in again to create a new one.
403 Forbidden, You are not subscribed to this product: {{partNumber}}

Image

Request Retrieves an image from a relative path
Url https://api.mcmaster.com/v1/images/{{imagePath}}
Method GET
Request Body N/A
Success Responses Example The requested image file
Codes 200 OK
Error Responses Example {
    "ErrorCode": 400,
    "ErrorMessage": "BAD_REQUEST",
    "ErrorDescription": "Invalid file path requested"
}
Codes 400 Bad Request, Invalid file path requested
400 Bad Request, Invalid file type requested
403 Forbidden, Invalid authorization token: {{authToken}}. Please log in again to create a new one.

CAD

Request Retrieves a CAD file from a relative path
Url https://api.mcmaster.com/v1/cad/{{cadPath}}
Method GET
Request Body N/A
Success Responses Example The requested CAD file
Codes 200 OK
Error Responses Example {
    "ErrorCode": 400,
    "ErrorMessage": "BAD_REQUEST",
    "ErrorDescription": "Invalid file path requested"
}
Codes 400 Bad Request, Invalid file path requested
400 Bad Request, Invalid file type requested
403 Forbidden, Invalid authorization token: {{authToken}}. Please log in again to create a new one.

Datasheet

Request Retrieves a datasheet from a relative path
Url https://api.mcmaster.com/v1/datasheets/{{dataSheetPath}}
Method GET
Request Body N/A
Success Responses Example The requested datasheet
Codes 200 OK
Error Responses Example {
    "ErrorCode": 400,
    "ErrorMessage": "BAD_REQUEST",
    "ErrorDescription": "Invalid file type requested"
}
Codes 400 Bad Request, Invalid file type requested
400 Bad Request, Invalid file path requested
403 Forbidden, Invalid authorization token: {{authToken}}. Please log in again to create a new one.

Last updated on 10/29/19