BOMs

Analyze a BOM

Submit a bill of materials for supply-chain risk analysis. Use it whenever your user asks to scan or analyze a BOM or a list of parts, even a list of one line. Every line is identified, its origin and current distributor availability resolved, and a risk score computed from manufacturing geography, live disruption exposure, lead-time volatility and sourcing gaps across the BOM.

The work runs in the background: this call answers 202 at once with the BOM id, and GET /v1/bom/{id} carries the report, partial while status is processing and full once it is complete. Time to complete varies with the parts in the BOM. One call carries up to 500 lines; a BOM is kept until you delete it.

POST

bom

Analyze a BOM

curl --request POST \
  --url https://api.partfinder.dev/v1/bom \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Controller board rev C",
  "parts": [
    {
      "mpn": "TPS54331DR",
      "manufacturer": "Texas Instruments",
      "quantity": 100,
      "supplier": "Mouser"
    },
    {
      "mpn": "STM32F407VGT6",
      "quantity": 50
    },
    {
      "mpn": "6305-2RS",
      "manufacturer": "SKF",
      "quantity": 10,
      "description": "Deep groove ball bearing"
    }
  ]
}
'

import requests

url = "https://api.partfinder.dev/v1/bom"

payload = {
    "name": "Controller board rev C",
    "parts": [
        {
            "mpn": "TPS54331DR",
            "manufacturer": "Texas Instruments",
            "quantity": 100,
            "supplier": "Mouser"
        },
        {
            "mpn": "STM32F407VGT6",
            "quantity": 50
        },
        {
            "mpn": "6305-2RS",
            "manufacturer": "SKF",
            "quantity": 10,
            "description": "Deep groove ball bearing"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Controller board rev C',
    parts: [
      {
        mpn: 'TPS54331DR',
        manufacturer: 'Texas Instruments',
        quantity: 100,
        supplier: 'Mouser'
      },
      {mpn: 'STM32F407VGT6', quantity: 50},
      {
        mpn: '6305-2RS',
        manufacturer: 'SKF',
        quantity: 10,
        description: 'Deep groove ball bearing'
      }
    ]
  })
};

fetch('https://api.partfinder.dev/v1/bom', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.partfinder.dev/v1/bom",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Controller board rev C',
    'parts' => [
        [
                'mpn' => 'TPS54331DR',
                'manufacturer' => 'Texas Instruments',
                'quantity' => 100,
                'supplier' => 'Mouser'
        ],
        [
                'mpn' => 'STM32F407VGT6',
                'quantity' => 50
        ],
        [
                'mpn' => '6305-2RS',
                'manufacturer' => 'SKF',
                'quantity' => 10,
                'description' => 'Deep groove ball bearing'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.partfinder.dev/v1/bom"

	payload := strings.NewReader("{\n  \"name\": \"Controller board rev C\",\n  \"parts\": [\n    {\n      \"mpn\": \"TPS54331DR\",\n      \"manufacturer\": \"Texas Instruments\",\n      \"quantity\": 100,\n      \"supplier\": \"Mouser\"\n    },\n    {\n      \"mpn\": \"STM32F407VGT6\",\n      \"quantity\": 50\n    },\n    {\n      \"mpn\": \"6305-2RS\",\n      \"manufacturer\": \"SKF\",\n      \"quantity\": 10,\n      \"description\": \"Deep groove ball bearing\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.partfinder.dev/v1/bom")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Controller board rev C\",\n  \"parts\": [\n    {\n      \"mpn\": \"TPS54331DR\",\n      \"manufacturer\": \"Texas Instruments\",\n      \"quantity\": 100,\n      \"supplier\": \"Mouser\"\n    },\n    {\n      \"mpn\": \"STM32F407VGT6\",\n      \"quantity\": 50\n    },\n    {\n      \"mpn\": \"6305-2RS\",\n      \"manufacturer\": \"SKF\",\n      \"quantity\": 10,\n      \"description\": \"Deep groove ball bearing\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.partfinder.dev/v1/bom")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Controller board rev C\",\n  \"parts\": [\n    {\n      \"mpn\": \"TPS54331DR\",\n      \"manufacturer\": \"Texas Instruments\",\n      \"quantity\": 100,\n      \"supplier\": \"Mouser\"\n    },\n    {\n      \"mpn\": \"STM32F407VGT6\",\n      \"quantity\": 50\n    },\n    {\n      \"mpn\": \"6305-2RS\",\n      \"manufacturer\": \"SKF\",\n      \"quantity\": 10,\n      \"description\": \"Deep groove ball bearing\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "as_of": "2026-09-28T15:49:42.444Z",
  "summary": "Accepted 3 lines. The BOM is being analyzed; poll GET /v1/bom/fc2b3371-7eb7-48cd-8847-70b2d76b0be8 until status is \"complete\".",
  "notice": "Informational only. Risk scores, stock levels, lead times and alternate-part suggestions may be incomplete, delayed or inaccurate. Independently verify before making procurement, engineering, compliance, safety or sourcing decisions.",
  "bom": {
    "id": "fc2b3371-7eb7-48cd-8847-70b2d76b0be8",
    "name": "Controller board rev C",
    "status": "processing",
    "lines": 3,
    "created_at": "2026-09-28T15:49:38.809Z"
  }
}

{
  "error": "authentication_required",
  "summary": "<string>",
  "reason": "<string>",
  "billing_url": "<string>",
  "did_you_mean": [
    "<string>"
  ]
}

{
  "error": "authentication_required",
  "summary": "<string>",
  "reason": "<string>",
  "billing_url": "<string>",
  "did_you_mean": [
    "<string>"
  ]
}

{
  "error": "credits_exhausted",
  "summary": "Your organization's credits for this month are used up, so this request was not run. Upgrade your plan in the PartFinder console at https://console.partfinder.dev/settings/billing, then try again.",
  "reason": "This request needs 75 credits and 0 are left.",
  "billing_url": "https://console.partfinder.dev/settings/billing"
}

{
  "error": "authentication_required",
  "summary": "<string>",
  "reason": "<string>",
  "billing_url": "<string>",
  "did_you_mean": [
    "<string>"
  ]
}

{
  "error": "authentication_required",
  "summary": "<string>",
  "reason": "<string>",
  "billing_url": "<string>",
  "did_you_mean": [
    "<string>"
  ]
}

{
  "error": "authentication_required",
  "summary": "<string>",
  "reason": "<string>",
  "billing_url": "<string>",
  "did_you_mean": [
    "<string>"
  ]
}

{
  "error": "authentication_required",
  "summary": "<string>",
  "reason": "<string>",
  "billing_url": "<string>",
  "did_you_mean": [
    "<string>"
  ]
}

Authorizations

Authorization

string

header

required

An API key created in the PartFinder console at https://console.partfinder.dev, or a customer key created with POST /v1/keys. Send as Authorization: Bearer <key>. Revocation takes effect within approximately one minute.

Headers

Idempotency-Key

string

Set by your client code, not by a person or a model: generate a new value (a UUID) for each submission, and send the same value again only when retrying that same request after a timeout. A retry with the same key returns the BOM the first request created instead of a duplicate. A key is recognised only from the same API key that sent it. The body is not compared, so never reuse a key for a different or updated BOM. A key is remembered for as long as the BOM it created exists; after that BOM is deleted, the same key starts a new one. Optional.

Body

application/json

parts

object[]

required

The BOM lines, up to 500 per call; more answers 422 bom_too_large. A file uploaded to POST /v1/bom/upload carries up to 2,000 rows in one BOM.

Required array length: 1 - 500 elements

Show child attributes

name

string

A label for this BOM, shown back in GET /v1/bom.

Maximum string length: 200

Response

Accepted. Analysis has started.

as_of

string<date-time>

required

ISO 8601. How current the data in this response is.

summary

string

required

Plain language an agent can relay without re-deriving it.

notice

string

required

Informational-use notice. Always present.

bom

object

required

Show child attributes

Analyze a BOM

curl --request POST \
  --url https://api.partfinder.dev/v1/bom \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Controller board rev C",
  "parts": [
    {
      "mpn": "TPS54331DR",
      "manufacturer": "Texas Instruments",
      "quantity": 100,
      "supplier": "Mouser"
    },
    {
      "mpn": "STM32F407VGT6",
      "quantity": 50
    },
    {
      "mpn": "6305-2RS",
      "manufacturer": "SKF",
      "quantity": 10,
      "description": "Deep groove ball bearing"
    }
  ]
}
'

import requests

url = "https://api.partfinder.dev/v1/bom"

payload = {
    "name": "Controller board rev C",
    "parts": [
        {
            "mpn": "TPS54331DR",
            "manufacturer": "Texas Instruments",
            "quantity": 100,
            "supplier": "Mouser"
        },
        {
            "mpn": "STM32F407VGT6",
            "quantity": 50
        },
        {
            "mpn": "6305-2RS",
            "manufacturer": "SKF",
            "quantity": 10,
            "description": "Deep groove ball bearing"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Controller board rev C',
    parts: [
      {
        mpn: 'TPS54331DR',
        manufacturer: 'Texas Instruments',
        quantity: 100,
        supplier: 'Mouser'
      },
      {mpn: 'STM32F407VGT6', quantity: 50},
      {
        mpn: '6305-2RS',
        manufacturer: 'SKF',
        quantity: 10,
        description: 'Deep groove ball bearing'
      }
    ]
  })
};

fetch('https://api.partfinder.dev/v1/bom', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.partfinder.dev/v1/bom",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Controller board rev C',
    'parts' => [
        [
                'mpn' => 'TPS54331DR',
                'manufacturer' => 'Texas Instruments',
                'quantity' => 100,
                'supplier' => 'Mouser'
        ],
        [
                'mpn' => 'STM32F407VGT6',
                'quantity' => 50
        ],
        [
                'mpn' => '6305-2RS',
                'manufacturer' => 'SKF',
                'quantity' => 10,
                'description' => 'Deep groove ball bearing'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.partfinder.dev/v1/bom"

	payload := strings.NewReader("{\n  \"name\": \"Controller board rev C\",\n  \"parts\": [\n    {\n      \"mpn\": \"TPS54331DR\",\n      \"manufacturer\": \"Texas Instruments\",\n      \"quantity\": 100,\n      \"supplier\": \"Mouser\"\n    },\n    {\n      \"mpn\": \"STM32F407VGT6\",\n      \"quantity\": 50\n    },\n    {\n      \"mpn\": \"6305-2RS\",\n      \"manufacturer\": \"SKF\",\n      \"quantity\": 10,\n      \"description\": \"Deep groove ball bearing\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.partfinder.dev/v1/bom")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Controller board rev C\",\n  \"parts\": [\n    {\n      \"mpn\": \"TPS54331DR\",\n      \"manufacturer\": \"Texas Instruments\",\n      \"quantity\": 100,\n      \"supplier\": \"Mouser\"\n    },\n    {\n      \"mpn\": \"STM32F407VGT6\",\n      \"quantity\": 50\n    },\n    {\n      \"mpn\": \"6305-2RS\",\n      \"manufacturer\": \"SKF\",\n      \"quantity\": 10,\n      \"description\": \"Deep groove ball bearing\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.partfinder.dev/v1/bom")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Controller board rev C\",\n  \"parts\": [\n    {\n      \"mpn\": \"TPS54331DR\",\n      \"manufacturer\": \"Texas Instruments\",\n      \"quantity\": 100,\n      \"supplier\": \"Mouser\"\n    },\n    {\n      \"mpn\": \"STM32F407VGT6\",\n      \"quantity\": 50\n    },\n    {\n      \"mpn\": \"6305-2RS\",\n      \"manufacturer\": \"SKF\",\n      \"quantity\": 10,\n      \"description\": \"Deep groove ball bearing\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "as_of": "2026-09-28T15:49:42.444Z",
  "summary": "Accepted 3 lines. The BOM is being analyzed; poll GET /v1/bom/fc2b3371-7eb7-48cd-8847-70b2d76b0be8 until status is \"complete\".",
  "notice": "Informational only. Risk scores, stock levels, lead times and alternate-part suggestions may be incomplete, delayed or inaccurate. Independently verify before making procurement, engineering, compliance, safety or sourcing decisions.",
  "bom": {
    "id": "fc2b3371-7eb7-48cd-8847-70b2d76b0be8",
    "name": "Controller board rev C",
    "status": "processing",
    "lines": 3,
    "created_at": "2026-09-28T15:49:38.809Z"
  }
}

{
  "error": "authentication_required",
  "summary": "<string>",
  "reason": "<string>",
  "billing_url": "<string>",
  "did_you_mean": [
    "<string>"
  ]
}

{
  "error": "authentication_required",
  "summary": "<string>",
  "reason": "<string>",
  "billing_url": "<string>",
  "did_you_mean": [
    "<string>"
  ]
}

{
  "error": "credits_exhausted",
  "summary": "Your organization's credits for this month are used up, so this request was not run. Upgrade your plan in the PartFinder console at https://console.partfinder.dev/settings/billing, then try again.",
  "reason": "This request needs 75 credits and 0 are left.",
  "billing_url": "https://console.partfinder.dev/settings/billing"
}

{
  "error": "authentication_required",
  "summary": "<string>",
  "reason": "<string>",
  "billing_url": "<string>",
  "did_you_mean": [
    "<string>"
  ]
}

{
  "error": "authentication_required",
  "summary": "<string>",
  "reason": "<string>",
  "billing_url": "<string>",
  "did_you_mean": [
    "<string>"
  ]
}

{
  "error": "authentication_required",
  "summary": "<string>",
  "reason": "<string>",
  "billing_url": "<string>",
  "did_you_mean": [
    "<string>"
  ]
}

{
  "error": "authentication_required",
  "summary": "<string>",
  "reason": "<string>",
  "billing_url": "<string>",
  "did_you_mean": [
    "<string>"
  ]
}

Overview

Endpoints

Analyze a BOM

Authorizations

Headers

Body

Response