# Credit Score API: What to Look For Before You Integrate > Most credit score API evaluations focus on the demo and skip the parts that hurt later: which score you actually get, what a no-hit costs, and how consent is recorded. Here's the checklist we'd use. Source: https://phonenumbercreditscore.com/blog/credit-score-api-guide Author: Jordan Avery, Head of Content Published: 2024-06-18 Updated: 2025-07-20 Topic: API & Developers Publisher: Phone Number Credit Score (https://phonenumbercreditscore.com/) A credit score API lets your software send a consumer's identifying details and get back a credit score, usually with some of the credit file behind it, in one request. Before you integrate one, check twelve things: which score model and version you get, which bureau it comes from, whether the pull is soft or hard, what else comes back with the score, how no-hits are handled and billed, latency, test keys, webhooks, how your permissible purpose is recorded, adverse action support, security controls and the real all-in price. That list looks long. In practice, three or four of those questions eliminate most vendors in the first call. We build and run a credit score API ourselves, and when a team tells us their first integration went sideways, the problem is almost never the JSON. It's a score model nobody checked, a pricing page that didn't mention no-hit charges, or a compliance review that started after launch. So that's where this checklist spends its time. ## The data: what you're actually buying ### 1. Which score model, and which version "Credit score" isn't a product. FICO alone has many versions in use, and myFICO keeps a [list of the FICO Score versions](https://www.myfico.com/credit-education/credit-scores/fico-score-versions) lenders use for mortgages, auto loans and cards. VantageScore has its own versions. They're built differently and can land dozens of points apart for the same person. Pick the model your decision rules were written for. If your credit policy says "620 minimum" because a mortgage investor said so, you want the score that investor means. In mortgage lending that has long meant the Classic FICO scores: FICO Score 2 from Experian, FICO® Score 4 from TransUnion and FICO Score 5 from Equifax. (That's starting to change: in July 2025 the FHFA said Fannie Mae and Freddie Mac would let lenders use VantageScore 4.0 too, with the implementation details still to come.) We go through the differences in [FICO vs. VantageScore](https://phonenumbercreditscore.com/blog/fico-vs-vantagescore) and [which scores mortgage lenders use](https://phonenumbercreditscore.com/blog/mortgage-credit-scores-fico-2-4-5). Our API returns FICO Score 4 by default, calculated by FICO from TransUnion data, and you can request VantageScore 4.0 instead with a single parameter if your investors or rules call for it. Whatever vendor you pick, get the model and version in writing, and make sure it's in the response body so your logs show what you scored on. ### 2. Which bureau Some APIs pull one bureau, some let you choose, some merge two or three. For pre-qualification and lead routing, one bureau is usually plenty. For underwriting, your investor may require more. Ask what's live today versus "available on request." ### 3. Soft pull or hard pull This one matters for the consumer. A soft inquiry doesn't affect their score and other lenders can't see it. A hard inquiry typically costs a few points and sits on their report for two years. Using a hard-pull endpoint for pre-qualification is the fastest way to generate complaints. More in our explainer on [soft pull vs. hard pull](https://phonenumbercreditscore.com/blog/soft-pull-vs-hard-pull). ### 4. What comes back besides the number A bare score is hard to act on. Useful extras, in rough order of value: - **Key factors (reason codes)** behind the score. You need these for adverse action notices, so a credit score API that omits them creates work for you later. - **File status flags**: frozen file, no file found, file too thin to score. Each one needs a different message to the consumer. - **Profile attributes**: utilization, total debt, on-time payment rate, inquiries, collections. - **Identity fields**: the name and current address on the file, so you can confirm you scored the right person. - **Account-level tradelines**, ideally as an optional add-on so you're not paying for them on every call. ## The plumbing: what your engineers will care about ### 5. Latency and timeouts Ask for p50 and p95, not an average. A soft-pull lookup that usually returns in a couple of seconds is fine to call synchronously from a form submit. If p95 is 20 seconds, design for async from day one. ### 6. Test keys that behave like production You want test keys that return realistic fixtures for each outcome: a strong file, a thin file, a frozen file, no match, an invalid number. If the sandbox only ever returns a 750, you'll find your edge-case bugs in production. ### 7. Webhooks and idempotency Webhooks let you fire off a lookup and handle the result when it lands, which keeps your app responsive and makes retries safe. Pair that with idempotency keys so a double-clicked submit doesn't pay for two reports. Our post on [routing leads by credit tier with webhooks](https://phonenumbercreditscore.com/blog/credit-webhooks-lead-routing) has a working pattern, and [adding phone-to-credit lookups to your CRM](https://phonenumbercreditscore.com/blog/phone-to-credit-lookup-crm-integration) covers the CRM side. ![A monitor and laptop on a desk showing lines of code, the setup where a credit score API integration gets built](https://phonenumbercreditscore.com/media/blog/01a1366e-d4ef-7863-a1a2-6a9c7f6c3643-1200.webp) Here's roughly what a request and response look like on ours, trimmed for space. It's an example with a fictional person: ``` POST /v1/lookups { "phone": "555-555-0178", "purpose": "consent" } 200 OK { "name": "Daniel Okafor", "address": { "city": "Columbus", "state": "OH" }, "phone_details": { "line_type": "mobile", "fraud_score": 8 }, "score": { "model": "FICO Score 4", "value": 721 } } ``` Notice the `purpose` field. That brings us to the part most evaluations skip. ## The compliance layer: the part that stalls launches ### 8. How your permissible purpose is captured Under the FCRA, you can only obtain a consumer report for a [permissible purpose listed in 15 U.S.C. § 1681b](https://www.law.cornell.edu/uscode/text/15/1681b), and consumer reporting agencies must have procedures to verify who their users are and what they're using reports for under [§ 1681e](https://www.law.cornell.edu/uscode/text/15/1681e). A well-designed credit score API asks you to state the purpose on every request and logs it next to the result. If a vendor's answer is "you agree to our terms once at signup," you'll be the one rebuilding that audit trail when a regulator or a consumer asks. Our [plain-English guide to permissible purpose](https://phonenumbercreditscore.com/blog/permissible-purpose-fcra) explains which purposes fit which use cases. The simplest purpose is the consumer's written OK. Build the consent checkbox into your form and pass that through. ### 9. Adverse action support If you deny credit or offer worse terms based on the report, you owe the consumer an adverse action notice that names the bureau, includes the score you used and lists its key factors. For credit decisions, Regulation B at [12 CFR § 1002.9](https://www.ecfr.gov/current/title-12/chapter-X/part-1002/section-1002.9) adds its own notice timing and content rules. The API should return everything the notice needs, in fields you can template from. ### 10. Security controls you can actually turn on Look for scoped API keys you can rotate, IP allow lists, team roles so a sales rep can't export everything, and usage logs your compliance person can read without a developer. If you're a lender, broker or dealer under the FTC's jurisdiction, the [Safeguards Rule at 16 CFR Part 314](https://www.ecfr.gov/current/title-16/chapter-I/subchapter-C/part-314) expects you to control access to customer information, and these features make that much easier to show. Also ask who holds the bureau relationship. Going direct to a bureau typically means a membership application, a site inspection of your office and annual security reviews. Many teams don't have weeks for that, which is why reseller APIs exist. ## The money: forecast it before you sign ### 11. The pricing model and the fine print Most credit score APIs charge some combination of a platform fee and a per-report fee. The questions that matter: - Are you charged when there's **no match** or a **frozen file**? (On ours, no match means no charge.) - Are there **monthly minimums** or setup fees? - What do **add-ons** cost, such as tradelines? - Can you set **spending limits** so a bug or a bot can't run up a five-figure bill overnight? ### 12. The real all-in number Do the arithmetic with your own volume. Our API is $49 a month or $149 a year, plus $7.50 per report, and there's no monthly cap. A team running 300 lookups a month pays $49 + (300 × $7.50) = $2,299 that month on the monthly plan. If a quarter of those also need tradelines, add $2 each for those 75, so $150 more. Reach 1,000 a month and you qualify for volume rates, which is a conversation with Bulk@PhoneNumberCreditScore.com. For a deeper model, see [how per-report credit API pricing works](https://phonenumbercreditscore.com/blog/credit-api-pricing-per-report) and, if you're processing lists, [bulk phone number credit lookups](https://phonenumbercreditscore.com/blog/bulk-phone-number-credit-lookup). Then compare that against what each lookup is worth. If one funded deal pays for 400 lookups, the per-report price matters less than the conversion lift from pre-qualifying people while they're still on the page. ## Credit score API red flags we'd walk away from A few things that should end a vendor call early: - They can't tell you the exact score model and version. - "Soft pull" is in the marketing but the contract says the endpoint may generate hard inquiries. - No reason codes in the response. - They'll let you score a purchased list without consent. That's not a feature. It's a liability you'd be inheriting. - No per-request purpose, no logs, no way to export an audit trail. - Pricing that only appears after a sales call. None of this is legal advice, and a fintech attorney is worth an hour of your time before launch. But if a credit score API passes all twelve checks above, the integration itself is usually the easy part. Our [API page](https://phonenumbercreditscore.com/api) has the full field list and pricing, and the [why FICO Score 4](https://phonenumbercreditscore.com/why-fico-4) page explains the default model in more detail. ## Frequently asked questions ### Do I need to be credentialed by a credit bureau to use a credit score API? Not always. Going direct to a bureau usually means a membership application, a site inspection and security reviews. Many API providers hold the bureau relationship themselves, so you sign up with them, state your permissible purpose for each pull and accept their terms instead. ### Will calling a credit score API hurt the consumer's score? It depends on the pull type. A soft pull doesn't affect the score and isn't visible to other lenders. A hard pull can cost a few points and shows up as an inquiry for two years. Ask every vendor which one their endpoint uses. ### Can I use a credit score API to screen a purchased lead list? Not without a permissible purpose for each person, which a purchased list doesn't give you. The usual route is to collect the consumer's consent at the point they ask for financing or a quote, then pull. ### How fast should a credit score API respond? For a single soft-pull lookup, a few seconds is typical. If a vendor's p95 latency is much higher, plan for asynchronous handling with webhooks rather than holding a web request open.