canonical: https://jentic.com/apis/jid.com/jid

# Jid API

The Jid API checks the business an agent is about to pay, sign with, book, hire, or buy from: whether it is real, active, licensed for the activity, and not sanctioned, with every fact cited to the registry that issued it. It resolves a name or identifier such as an LEI, EIN, DUNS, NPI, or USDOT number to a Jid file, verifies that file and, given an activity like haul_freight or sell_alcohol plus a jurisdiction or amount, returns a proceed, review, stop, or insufficient_data decision with an Ed25519-signed receipt. A screen operation gives a deterministic engage-or-not answer from a domain, email, phone, or company name, an email check reads raw headers for SPF, DKIM, DMARC, and lookalike domains, and keyed accounts can qualify inbound leads and monitor files for changes. It provides business information only, not consumer reports.

## For AI agents

Verify a business against official registries before acting, get a proceed, review, or stop decision with a signed receipt, screen domains and emails for engage-or-not answers, qualify leads, and monitor business files for changes.

## Scope

Does not verify individual consumers, produce credit or FCRA consumer reports, or give legal advice. Use for registry-cited business verification and engage-or-not screening only.

## Capabilities

- Resolve a business name or identifier (FEI, LEI, CIK, DUNS, NPI, EIN, UEI, USDOT, state numbers) to candidate Jid files with GET `/v1/search`
- Verify a business with GET `/v1/entities/{id}/verify` and, with an activity, jurisdiction, or amount, get a decision of proceed, review, stop, or insufficient_data plus a signed receipt
- Read the full business file with location, owner statements, possible matches, and the last 50 change events via GET `/v1/entities/{id}`
- Get an engage-or-not answer with risk, reasons, and mitigations from a domain, url, email, phone, or company_name with POST `/v1/screen`
- Check whether an email is really from who it says by passing raw headers to POST `/v1/email-check` for SPF, DKIM, DMARC, and lookalike-domain checks
- Qualify an inbound lead or counterparty with legitimacy, capacity, and consistency scores via POST `/v1/qualify`
- Watch a business file and receive each change with old and new values at a webhook_url with POST `/v1/monitors`

## Use cases

### Pre-payment counterparty checks through Jentic

An agent about to pay, book, or sign with a business should check it first. Through Jentic it finds the Jid operations by intent: GET `/v1/search` turns the name or identifier into a file id, and GET `/v1/entities/{id}/verify` with an activity, jurisdiction, and amount returns proceed, review, stop, or insufficient_data with reasons and a signed receipt. The agent acts only on proceed, and the jid_live_ key is injected at call time and never sits in its context.

Example prompt: Call GET `/v1/search` with q set to the supplier's EIN, then GET `/v1/entities/{id}/verify` with activity 'general_commerce', jurisdiction 'US-CO', amount 20000, and currency 'USD', and continue only if decision is 'proceed'

### Phishing and invoice-fraud screening

Payment-redirect scams arrive as convincing emails. POST `/v1/email-check` reads the receiving server's Authentication-Results, Received-SPF, DKIM alignment with From, Reply-To versus From, and whether the From domain imitates a known company's registered domain, returning checks and a read of engage, verify_first, or do_not_engage. POST `/v1/screen` gives a deterministic engage-or-not answer from the sender's domain or email with reasons and sources.

Example prompt: Call POST `/v1/email-check` with headers set to the raw message headers, and if the read is 'do_not_engage' or 'verify_first', flag the email instead of paying

### Inbound lead qualification

Sales teams waste time on junk form submissions. POST `/v1/qualify` checks the domain's MX, SPF, DMARC, and registration date, matches it to a Jid file, and returns legitimacy, capacity, and consistency scores from 0 to 100 with reasons, a recommendation, and questions to ask. POST `/v1/outcomes` records what you decided, such as legit or spam, which tunes the published rules.

Example prompt: Call POST `/v1/qualify` with email and company_name from the form, then after the call with the lead record POST `/v1/outcomes` with result_id and outcome 'legit' or 'spam'

### Ongoing vendor monitoring

A vendor that was licensed at onboarding may not stay that way. POST `/v1/monitors` watches a Jid file by entity_id and delivers each change with old and new values to a webhook_url or email; GET `/v1/monitors` lists monitors and DELETE `/v1/monitors` removes one by id.

Example prompt: Call POST `/v1/monitors` with entity_id set to the vendor's Jid file id and webhook_url set to your alerts endpoint

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/v1/search` | Resolve a name or registry number to candidate files |
| GET | `/v1/entities/{id}/verify` | Verify a business and get a decision |
| GET | `/v1/entities/{id}` | Get the full business file |
| POST | `/v1/screen` | Engage-or-not screen |
| POST | `/v1/email-check` | Check email headers |
| POST | `/v1/qualify` | Qualify a lead or counterparty |
| GET | `/v1/receipts/{receipt_id}` | Retrieve a signed receipt |
| POST | `/v1/monitors` | Watch a business file |

## Key resources

- **Business files** — Registry-cited facts on a business: status, licences, flags, owners, location, and change events
- **Decisions and receipts** — Proceed, review, stop, or insufficient_data decisions with Ed25519-signed receipts kept 13 months
- **Screens** — Engage-or-not answers with risk, confidence, reasons, and mitigations
- **Qualifications and outcomes** — Lead scores with recommendations, and the outcomes you record
- **Monitors** — Watches on business files that deliver changes by webhook or email

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 62 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 77 / 100
  - Developer Experience & Jentic Compatibility: 62 / 100
  - AI-Readiness & Agent Experience: 43 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 78 / 100
- **View full report:** https://jentic.com/apis/jid.com/jid/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Jid by hand means handling its optional jid_live_ bearer key, knowing which operations need it, and chaining search into verify with the right activity and jurisdiction codes. Through Jentic you install once, import the Jid API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Jid puts the business file id in the URL path (`/v1/entities/{id}/verify`), so a rule can pin your agent to checking one named business. You choose the operations it may call, so monitor creation or deletion and outcome reporting are not included unless you add them.
- **Credential handling:** Your Jid key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'verify a business before paying' or 'is this email really from them', and Jentic returns the matching Jid operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **OpenCorporates API** — Global company registry records
- **OpenSanctions API** — Sanctions and politically exposed persons screening
- **UK Companies House** — Official UK company filings and officers
- **Sumsub API** — KYC and KYB onboarding with document checks

## FAQ

### Is there a Jid MCP server?

You don't need an MCP server to give your agent the Jid API. Jentic connects it directly from the API Directory: import it, store your Jid key once, and your agent calls it. Operations are discovered on demand, so no extra tool definitions sit in the agent's context.

### What authentication does the Jid API use?

Per its OpenAPI spec, the Jid API takes a jid_live_ key sent as a bearer token in the Authorization header. The key is optional on search, verify, screen, and email-check, which run on a per-IP free tier without one, and required on POST `/v1/qualify`, GET `/v1/results`, and the monitors operations. GET `/v1/signal` is open and called from the visitor's browser. Through Jentic, the key is stored encrypted by your own Jentic One instance and injected at call time.

### What are the rate limits for the Jid API?

Per the OpenAPI spec, calls without a key are limited to 10 requests a minute and 100 a day per IP. A free key, with no card, includes 1,000 checks a month, and POST `/v1/qualify` counts as 2 checks. See https://jid.com/pricing for paid tiers.

### Can I limit what my agent is allowed to do with the Jid API?

Yes. For example, write a rule that allows only GET `/v1/search` and GET `/v1/entities/{id}/verify.` Your agent can then look up and verify businesses but cannot create or delete monitors or record outcomes, and every call it makes is logged.

### Is a Jid decision legal advice?

No. Decisions apply Jid's published decision rules and are not legal advice, and the data is business information only, not a consumer report and not for FCRA purposes. Act only on proceed: requirements Jid cannot check are treated as unknown and lead to review.

### How do I verify a business through Jentic?

Search Jentic for 'verify a business before paying', load the verifyBusiness operation, and call GET `/v1/entities/{id}/verify` with the file id from GET `/v1/search` plus an activity and jurisdiction to get a decision and signed receipt. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can someone else check a Jid receipt?

Yes. GET `/v1/receipts/{receipt_id}` is free and readable by anyone holding the receipt id, so it can be shown to an auditor or counterparty, who can verify signature.sig against the key published at /.well-known/jid-keys.json.