# Platinux API documentation > Score companies by buying intent, look up company details and find the company behind an email, with one API key. # Introduction > What the Platinux API does, how to call it, and every endpoint at a glance. The Platinux API lets your own systems do what the Platinux app does: **score a company by its buying signals**, **look up company details** and **find the company behind an email address**. Everything works with one API key, and uses the same templates and credits as your Platinux account. ## The flow: template first, then score Every score needs a template, so the order is always the same: 1. **Get an API key** at [platinux.net/dashboard/score](https://platinux.net/dashboard/score). 2. **Get your template.** Call [`GET api-templates`](/templates) and take the `template_id` with `"is_live": true`. The template decides which buying signals count towards the score. 3. **Score**, passing that `template_id`: a domain, email or LinkedIn URL with [`/score/domain`](/score-domain), [`/score/email`](/score-email) or [`/score/social`](/score-social), or a whole list with [`/score/…/bulk`](/score-list). Scoring runs in the background: you start a job, then check back for the score. 4. **Add company details** with [`api-company`](/company) whenever you need them. ## Use cases | You want to | Start here | |---|---| | Reach out first to the target accounts most likely to buy | [B2B sales outreach](/b2b-sales-outreach) | | Give your best-fit form fills and demo requests the fastest path | [Conversion rate optimisation](/conversion-rate-optimisation) | | Find the signups worth a sales conversation | [Identify good leads from signups](/signup-lead-qualification) | ## Base URL ```text https://mmkuffhlzytnmgraagbp.supabase.co/functions/v1 ``` Every request uses HTTPS and JSON. Send your API key in the `Authorization` header (see [Authentication](/authentication)). ## Endpoints **Scoring**: start with whatever you have (each call needs a `template_id` from `api-templates`): | Endpoint | What you send | Credits | |---|---|---| | [`POST /score/domain`](/score-domain) | A company website | 10 | | [`POST /score/email`](/score-email) | A company, work or generic email | 10 (generic 20) | | [`POST /score/social`](/score-social) | A LinkedIn company page or person profile | 10 | | [`POST /score/…/bulk`](/score-list) | Up to 1,000 of the above | Per input | | [`GET api-templates`](/templates) | Lists your scoring templates | Free | Anything that ends without a score costs **0**. **Company data**: | Endpoint | What it does | Credits | |---|---|---| | [`api-company`](/company) / [`-bulk`](/company-bulk) | Company details for a domain (up to 1,000) | 1 when found | | [`api-email-domain`](/email-domain) / [`-bulk`](/email-domain-bulk) | The company domain behind an email (up to 1,000) | 0, or 10 for a generic email found | New here? The [Quickstart](/quickstart) gets you from a new key to your first score in a few minutes. ## For AI tools These docs are plain to read for people and for AI assistants: - [`/llms.txt`](/llms.txt): an index of every page. - [`/llms-full.txt`](/llms-full.txt): the whole documentation in one Markdown file. - Add `.md` to any page address for its Markdown, for example [`/score-domain.md`](/score-domain.md). - [`/openapi.json`](/openapi.json): the OpenAPI 3.1 description of every endpoint. --- # Quickstart > From a new API key to your first company score in a few minutes. The flow is always: **API key → get your template → score → check back for the result.** You need the template before you can score. ## 1. Create an API key Go to [platinux.net/dashboard/score](https://platinux.net/dashboard/score) and create a key. Copy the key straight away: it is shown only once. It looks like `plx_live_` followed by 32 letters and numbers. Keep it in an environment variable on your server: ```bash export PLATINUX_API_KEY="plx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" export BASE="https://mmkuffhlzytnmgraagbp.supabase.co/functions/v1" ``` ## 2. Get your template (before scoring) ```bash curl "$BASE/api-templates" -H "Authorization: Bearer $PLATINUX_API_KEY" ``` ```json { "templates": [ { "template_id": "4d286e65-11b6-4f86-8eff-2a41105b0e09", "name": "Platinux", "is_live": true, "scoreable": true } ] } ``` Use the template with `"is_live": true`. Every scoring call needs its `template_id`. ## 3. Score a domain with that template ```bash curl -X POST "$BASE/score/domain" \ -H "Authorization: Bearer $PLATINUX_API_KEY" -H "Content-Type: application/json" \ -d '{"domain": "acme.com", "template_id": "4d286e65-11b6-4f86-8eff-2a41105b0e09"}' ``` A new domain starts a job and answers `202`: ```json { "status": "processing", "job_id": "1f6c2a90-…", "domain": "acme.com", "template_id": "4d286e65-…", "check_after_seconds": 30 } ``` ## 4. Check until it's finished ```bash curl "$BASE/score/domain?job_id=1f6c2a90-…" -H "Authorization: Bearer $PLATINUX_API_KEY" ``` When `status` is no longer `processing`, the score is ready (`200`): ```json { "status": "complete", "job_id": "1f6c2a90-…", "domain": "acme.com", "template_id": "4d286e65-…", "score": 75, "scored_at": "2026-11-19T10:20:00Z", "credits_charged": 10 } ``` A domain usually takes 1 to 3 minutes and costs 10 credits. Have an email or a LinkedIn URL instead? Use [`/score/email`](/score-email) or [`/score/social`](/score-social) the same way. ## The same in code ```javascript const BASE = "https://mmkuffhlzytnmgraagbp.supabase.co/functions/v1"; const headers = { Authorization: `Bearer ${process.env.PLATINUX_API_KEY}`, "Content-Type": "application/json" }; async function score(domain, templateId) { let r = await fetch(`${BASE}/score/domain`, { method: "POST", headers, body: JSON.stringify({ domain, template_id: templateId }) }); let job = await r.json(); if (!r.ok) throw new Error(job.reason ?? job.error); while (job.status === "processing") { await new Promise((ok) => setTimeout(ok, (job.check_after_seconds ?? 30) * 1000)); job = await (await fetch(`${BASE}/score/domain?job_id=${job.job_id}`, { headers })).json(); } return job.score; } ``` ```python import os, time, requests BASE = "https://mmkuffhlzytnmgraagbp.supabase.co/functions/v1" H = {"Authorization": f"Bearer {os.environ['PLATINUX_API_KEY']}"} def score(domain, template_id): r = requests.post(f"{BASE}/score/domain", headers=H, json={"domain": domain, "template_id": template_id}) job = r.json() if r.status_code >= 400: raise RuntimeError(job.get("reason") or job["error"]) while job["status"] == "processing": time.sleep(job.get("check_after_seconds", 30)) job = requests.get(f"{BASE}/score/domain", headers=H, params={"job_id": job["job_id"]}).json() return job["score"] ``` ## Next - Score a whole list at once with [Score a list](/score-list). - See every error and what to do about it in [Errors](/errors). --- # Authentication > How API keys work, how to send them, and how to keep them safe. Every request needs **your API key**. The key tells us which account is calling, so your templates and credits are used. You never send a user ID. ## Sending the key Put it in the `Authorization` header: ```http Authorization: Bearer plx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ``` The header `x-api-key: plx_live_…` works too. A missing, wrong or revoked key gets `401`: ```json { "error": "unauthorized", "message": "send your API key: Authorization: Bearer plx_live_…" } ``` ## Creating and revoking keys | | | |---|---| | **Where** | [platinux.net/dashboard/score](https://platinux.net/dashboard/score) | | **Format** | `plx_live_` followed by 32 letters and numbers | | **Shown** | **Once**, when you create it. We store only a fingerprint, so a lost key can't be recovered; create a new one | | **How many** | Up to **5 active keys** per account | | **Revoking** | Click **Revoke**. The key stops working on the very next request | | **Last used** | The keys page shows when each key was last used | Give each system its own key (for example "CRM sync" and "Zapier"), so you can revoke one without touching the others. ## Keeping keys safe - **Use keys only on your server.** Never put a key in a web page, a mobile app or anything others can download: anyone with the key can spend your credits. - **Keep keys out of code.** Load them from environment variables or a secrets manager, not from files in your repository. - **Revoke a leaked key at once,** then create a new one. ## CORS The API sends CORS headers and answers browser preflight requests. That is for the Platinux app itself, which calls the API with the signed-in user's session. **Your own integrations should call the API from a server**, with a key. --- # Credits > What each call costs, when credits are charged, and what is free. The API uses the same credits as your Platinux account. Each response shows what it cost in `credits_charged`. ## Price list **Scoring**: one charge per scored input, only when scoring happens: | What you send | Endpoint | Credits | |---|---|---| | Company domain | `/score/domain` | **10** | | LinkedIn company page | `/score/social` | **10** | | LinkedIn person profile | `/score/social` | **10** | | Company email (`info@acme.com`) | `/score/email` | **10** | | Work email (`jane@acme.com`) | `/score/email` | **10** | | Generic email (`jane@gmail.com`) | `/score/email` | **20** | | Anything that isn't scored (invalid, not found, temporary email, rejected website) | any | **0** | Every run is scored and charged again. In a list, inputs that lead to the same company are scored and charged once. **Company data:** | Call | Credits | |---|---| | List templates | Free | | Company details, found | 1 (free again within 30 days) | | Company details, not found | Free | | Email → domain, work or temporary email | Free | | Email → domain, generic email found | 10 (free again within 30 days) | | Email → domain, nothing found | Free | | A data source not answering (`502`) | Free | ## Checks before charging - **Enough credits first:** if your balance can't cover the most a call might cost, it is refused with `402 insufficient_credits` and nothing is charged. - **Bulk calls are checked up front:** a bulk score needs credits for every new domain in the list before it starts. - **Never charged twice:** two identical requests at the same time start one job and charge once. Top up credits in the Platinux app. --- # B2B sales outreach > Score your target accounts by buying intent, so your team reaches out to the companies most likely to buy first. You have a list of companies you could sell to. Platinux scores each one from 0 to 100 on how strongly it is showing buying signals right now. Your team works the list from the top. ## What you send Whatever your list holds: | Your list has | Endpoint | |---|---| | Company websites | [`/score/domain/bulk`](/score-list) | | LinkedIn company pages or people's profiles | [`/score/social/bulk`](/score-list) | | Contacts' email addresses | [`/score/email/bulk`](/score-list) | ## The flow 1. **Get your template.** Call [`GET api-templates`](/templates) and take the `template_id` with `"is_live": true`. The template decides which buying signals count. Set it up in the app first, with the signals that matter for what you sell. 2. **Score the list.** Send up to 1,000 inputs in one call: ```bash curl -X POST "https://mmkuffhlzytnmgraagbp.supabase.co/functions/v1/score/domain/bulk" \ -H "Authorization: Bearer $PLATINUX_API_KEY" -H "Content-Type: application/json" \ -d '{"template_id": "4d286e65-…", "inputs": ["acme.com", "globex.com", "initech.com"]}' ``` 3. **Check back** with the `batch_id` until `status` is `complete` (see [Score a list](/score-list)). 4. **Sort by `score`, highest first,** and start outreach at the top. 5. **Add company details** for the accounts you'll contact (size, industry, location) with [`api-company-bulk`](/company-bulk), 1 credit per company found. ## Tips - Rescore your list regularly. Signals change, and a company that was quiet last month may be buying now. Every run is charged again. - In a list, inputs that lead to the same company are scored and charged once. - Inputs that aren't real company websites are rejected for free (see [Domain checks](/domain-checks)). --- # Conversion rate optimisation > Score the company behind each form fill or demo request, and give your best-fit visitors the fastest path to buy. Not every form fill deserves the same follow-up. Score the company behind each one as it arrives, then give high scores the fast path (a sales call, a calendar link, a tailored offer) and send the rest to self-serve or nurture. ## The flow 1. **Get your template once.** Call [`GET api-templates`](/templates) and keep the `template_id` with `"is_live": true` in your config. 2. **Score each submission** from the email the visitor typed: ```bash curl -X POST "https://mmkuffhlzytnmgraagbp.supabase.co/functions/v1/score/email" \ -H "Authorization: Bearer $PLATINUX_API_KEY" -H "Content-Type: application/json" \ -d '{"email": "jane@acme.com", "template_id": "4d286e65-…"}' ``` 3. **Check back** with the `job_id` (see [Score from an email](/score-email)). A score usually takes 1 to 3 minutes, so route the follow-up, not the page the visitor is looking at. 4. **Act on the score:** push it to your CRM or marketing tool and branch on it. ## What different emails cost | Email | What happens | Credits | |---|---|---| | Work (`jane@acme.com`) | Scored from the email's domain | 10 | | Generic (Gmail, Outlook, etc.) | We find the person's current employer, then score it | 20 | | Temporary (`x@mailinator.com`) | Not scored: `status: "temporary_email"` | 0 | ## Tips - Want only the company first, without a score? [`api-email-domain`](/email-domain) is free for work and temporary emails. - Use the same template for every form, so scores are comparable across pages and campaigns. --- # Identify good leads from signups > Score every new signup's company, so sales spends time on the accounts that can become customers. Most product signups never buy. Score the company behind each new signup's email, and send the high scorers to sales while the rest carry on self-serve. ## The flow 1. **Get your template once.** Call [`GET api-templates`](/templates) and keep the `template_id` with `"is_live": true`. 2. **When someone signs up, score their email** from your backend: ```bash curl -X POST "https://mmkuffhlzytnmgraagbp.supabase.co/functions/v1/score/email" \ -H "Authorization: Bearer $PLATINUX_API_KEY" -H "Content-Type: application/json" \ -d '{"email": "jane.doe@gmail.com", "template_id": "4d286e65-…"}' ``` 3. **Check back** with the `job_id` until the score is ready ([Score from an email](/score-email)). 4. **Save the score on the user** in your database or CRM, and alert sales above a threshold you choose. Have a backlog of past signups? Send up to 1,000 emails at once with [`/score/email/bulk`](/score-list). ## Signups with generic and temporary emails | Email | What happens | Credits | |---|---|---| | Work (`jane@acme.com`) | Scored from the email's domain | 10 | | Generic (Gmail, Outlook, etc.) | We find the person's current employer, then score it | 20, or 0 if no employer is found | | Temporary (`x@mailinator.com`) | Not scored: `status: "temporary_email"`. A useful sign of a low-quality signup | 0 | ## Tips - The score is for the signup's **company**, not the person. - To screen out temporary emails before spending credits, call [`api-email-domain`](/email-domain) first: it is free for work and temporary emails. --- # List templates > The scoring templates your account can use, and which one is live. `GET https://mmkuffhlzytnmgraagbp.supabase.co/functions/v1/api-templates` A template decides which buying signals count towards a score. You create and edit templates in the Platinux app; the API only lists them. ## Request ```bash curl "https://mmkuffhlzytnmgraagbp.supabase.co/functions/v1/api-templates" -H "Authorization: Bearer $PLATINUX_API_KEY" ``` No parameters. ## Response `200` ```json { "templates": [ { "template_id": "4d286e65-11b6-4f86-8eff-2a41105b0e09", "name": "Platinux", "is_live": true, "scoreable": true }, { "template_id": "00000000-0000-4000-8000-000000000001", "name": "Default (No Signals)", "is_live": false, "scoreable": false } ] } ``` | Field | Type | Meaning | |---|---|---| | `template_id` | string (UUID) | Pass this to every scoring endpoint ([`/score/domain`](/score-domain), [`/score/email`](/score-email), [`/score/social`](/score-social)) | | `name` | string | The template's name in the app | | `is_live` | boolean | `true` for your active template. **Scoring uses this one only** (see [Limits](/limits)) | | `scoreable` | boolean | `false` when the template has no signals switched on; scoring with it returns `422 template_empty` | The live template comes first. An account with no templates gets `{ "templates": [] }`. The response never includes a template's signals or settings. ## Errors | HTTP | `error` | |---|---| | 401 | `unauthorized` | | 405 | `method_not_allowed` | --- # Score a domain > Score a company from its website domain. 10 credits. `POST https://mmkuffhlzytnmgraagbp.supabase.co/functions/v1/score/domain` Scoring checks a company's buying signals with your live template and returns one number from 0 to 100. It runs in the background: **start** a job, then **check** it. Other inputs: [email](/score-email), [LinkedIn URL](/score-social), or [a whole list](/score-list). ## Start ```bash curl -X POST "https://mmkuffhlzytnmgraagbp.supabase.co/functions/v1/score/domain" \ -H "Authorization: Bearer $PLATINUX_API_KEY" -H "Content-Type: application/json" \ -d '{"domain": "asana.com", "template_id": "4d286e65-11b6-4f86-8eff-2a41105b0e09"}' ``` | Body field | Type | Required | Notes | |---|---|---|---| | `domain` | string | Yes | The company's website. `https://www.Asana.com/pricing` is cleaned to `asana.com` | | `template_id` | string (UUID) | Yes | Your live template, from [`api-templates`](/templates) | The domain is screened first: social links, file names, IP addresses, parked domains and similar inputs are rejected with a one-word `reason` and cost nothing ([Domain checks](/domain-checks)). ### Started: `202`, 10 credits ```json { "status": "processing", "job_id": "8184a513-…", "domain": "asana.com", "template_id": "4d286e65-…", "check_after_seconds": 30, "input": "asana.com", "input_type": "domain", "credits_charged": 10 } ``` **Every run scores again and is charged again.** If the same company is already being scored for your account, that running job is returned instead, free. ## Check the score ```bash curl "https://mmkuffhlzytnmgraagbp.supabase.co/functions/v1/score/domain?job_id=8184a513-…" -H "Authorization: Bearer $PLATINUX_API_KEY" ``` `202` while `processing`; `200` when finished. Check every `check_after_seconds` (30). Any of the three paths works for `GET`. ```json { "status": "complete", "job_id": "8184a513-…", "domain": "asana.com", "template_id": "4d286e65-…", "score": 100, "scored_at": "2026-11-19T14:48:49Z", "credits_charged": 10 } ``` `status` is `complete`, or `partial` when some data didn't arrive within 10 minutes (scored with what arrived). ## Errors | HTTP | `error` | When | |---|---|---| | 400 | `invalid_domain` | Not a company website; `reason` says why. Free | | 400 | `invalid_input` | Missing or malformed `template_id` / `job_id` | | 401 | `unauthorized` | Missing, wrong or revoked key | | 402 | `insufficient_credits` | Fewer than 10 credits | | 403 | `template_not_allowed` | The template isn't yours | | 404 | `job_not_found` | Wrong `job_id` | | 409 | `template_not_live` | Use the template with `is_live: true` | | 422 | `template_empty` | Your live template has nothing switched on | --- # Score from an email > Score the company behind any email: company or work email 10 credits, generic email 20. `POST https://mmkuffhlzytnmgraagbp.supabase.co/functions/v1/score/email` Send an email address; we find the company and score it in one call. | Email | Example | How we find the company | Credits | |---|---|---|---| | **Company** | `info@acme.com` | The email's own domain | **10** | | **Work** | `jane@mail.acme.com` | The email's own domain → `acme.com` | **10** | | **Generic** (Gmail, Outlook, etc.) | `jane.doe@gmail.com` | The person's professional profile → their **current** employer → its website | **20** | | **Temporary** | `x@mailinator.com` | None: there is no company | **0** | **You're only charged when scoring happens.** No company found, a temporary email, or a rejected company website all cost 0. The score is **for the person's company**, not the person. ## Start ```bash curl -X POST "https://mmkuffhlzytnmgraagbp.supabase.co/functions/v1/score/email" \ -H "Authorization: Bearer $PLATINUX_API_KEY" -H "Content-Type: application/json" \ -d '{"email": "jane.doe@gmail.com", "template_id": "4d286e65-…"}' ``` | Body field | Type | Required | |---|---|---| | `email` | string | Yes | | `template_id` | string (UUID) | Yes | ### Company found, scoring started: `202` ```json { "status": "processing", "job_id": "fba400cc-…", "domain": "acme.com", "template_id": "4d286e65-…", "check_after_seconds": 30, "input": "jane.doe@gmail.com", "input_type": "personal_email", "credits_charged": 20 } ``` ### No company: `200`, 0 credits ```json { "status": "not_found", "input": "someone@gmail.com", "input_type": "personal_email", "domain": null, "score": null, "credits_charged": 0 } ``` ```json { "status": "temporary_email", "input": "x@mailinator.com", "input_type": "temporary_email", "domain": null, "score": null, "credits_charged": 0 } ``` `input_type`: `work_email` (work and company emails), `personal_email` (a generic email such as Gmail or Outlook) or `temporary_email`. ## Check the score ```bash curl "https://mmkuffhlzytnmgraagbp.supabase.co/functions/v1/score/domain?job_id=8184a513-…" -H "Authorization: Bearer $PLATINUX_API_KEY" ``` `202` while `processing`; `200` when finished. Check every `check_after_seconds` (30). Any of the three paths works for `GET`. ```json { "status": "complete", "job_id": "8184a513-…", "domain": "asana.com", "template_id": "4d286e65-…", "score": 100, "scored_at": "2026-11-19T14:48:49Z", "credits_charged": 10 } ``` `status` is `complete`, or `partial` when some data didn't arrive within 10 minutes (scored with what arrived). ## Errors | HTTP | `error` | When | |---|---|---| | 400 | `invalid_email` | Not a valid email address | | 400 | `invalid_domain` | The company's website was rejected ([Domain checks](/domain-checks)). Free | | 401 | `unauthorized` | Missing, wrong or revoked key | | 402 | `insufficient_credits` | Balance below the price (10, or 20 for a generic email) | | 403 / 409 / 422 | `template_not_allowed` / `template_not_live` / `template_empty` | Template problems | | 502 | `provider_unavailable` | A data source didn't answer while finding the company. Free; try again | --- # Score from LinkedIn > Score a company from its LinkedIn page, or from a person's LinkedIn profile (their current employer). 10 credits. `POST https://mmkuffhlzytnmgraagbp.supabase.co/functions/v1/score/social` | URL | Example | Company scored | Credits | |---|---|---|---| | **Company page** | `linkedin.com/company/stripe` | That company (its website, e.g. `stripe.com`) | **10** | | **Person profile** | `linkedin.com/in/jane-doe` | The person's **current** employer | **10** | `/company/`, `/school/` and `/showcase/` pages are company pages; `/in/` is a person. Any form works (`https://`, `www.`, trailing slash, query). ## Start ```bash curl -X POST "https://mmkuffhlzytnmgraagbp.supabase.co/functions/v1/score/social" \ -H "Authorization: Bearer $PLATINUX_API_KEY" -H "Content-Type: application/json" \ -d '{"url": "https://www.linkedin.com/company/stripe/", "template_id": "4d286e65-…"}' ``` | Body field | Type | Required | |---|---|---| | `url` | string | Yes | | `template_id` | string (UUID) | Yes | ### Company found, scoring started: `202`, 10 credits ```json { "status": "processing", "job_id": "8394d14a-…", "domain": "stripe.com", "template_id": "4d286e65-…", "check_after_seconds": 30, "input": "https://www.linkedin.com/company/stripe", "input_type": "linkedin_company", "credits_charged": 10 } ``` ### No company found: `200`, 0 credits ```json { "status": "not_found", "input": "https://www.linkedin.com/in/someone", "input_type": "linkedin_person", "domain": null, "score": null, "credits_charged": 0 } ``` `input_type`: `linkedin_company` or `linkedin_person`. ## Check the score ```bash curl "https://mmkuffhlzytnmgraagbp.supabase.co/functions/v1/score/domain?job_id=8184a513-…" -H "Authorization: Bearer $PLATINUX_API_KEY" ``` `202` while `processing`; `200` when finished. Check every `check_after_seconds` (30). Any of the three paths works for `GET`. ```json { "status": "complete", "job_id": "8184a513-…", "domain": "asana.com", "template_id": "4d286e65-…", "score": 100, "scored_at": "2026-11-19T14:48:49Z", "credits_charged": 10 } ``` `status` is `complete`, or `partial` when some data didn't arrive within 10 minutes (scored with what arrived). ## Errors | HTTP | `error` | When | |---|---|---| | 400 | `invalid_url` | Not a LinkedIn company or person URL (`reason: not_linkedin`) | | 400 | `invalid_domain` | The company's website was rejected ([Domain checks](/domain-checks)). Free | | 401 | `unauthorized` | Missing, wrong or revoked key | | 402 | `insufficient_credits` | Fewer than 10 credits | | 403 / 409 / 422 | `template_not_allowed` / `template_not_live` / `template_empty` | Template problems | | 502 | `provider_unavailable` | A data source didn't answer. Free; try again | --- # Score a list > Score up to 1,000 domains, emails or LinkedIn URLs in one call. Same prices per input; one score per company. `POST https://mmkuffhlzytnmgraagbp.supabase.co/functions/v1/score/{domain|email|social}/bulk` Add `/bulk` to any scoring path to send a list. Each input is handled and priced exactly as on its single page ([domain](/score-domain), [email](/score-email), [LinkedIn](/score-social)). ## Start ```bash curl -X POST "https://mmkuffhlzytnmgraagbp.supabase.co/functions/v1/score/domain/bulk" \ -H "Authorization: Bearer $PLATINUX_API_KEY" -H "Content-Type: application/json" \ -d '{"template_id": "4d286e65-…", "inputs": ["notion.so", "https://www.notion.so/pricing", "linear.app", "logo.png"]}' ``` | Body field | Type | Required | Notes | |---|---|---|---| | `template_id` | string (UUID) | Yes | Your live template | | `inputs` | array of strings | Yes | 1 to 1,000. Also accepted as `domains`, `emails` or `urls` | ### Started: `202` ```json { "batch_id": "a3a4f2e6-…", "accepted": 3, "rejected": [ { "input": "logo.png", "reason": "file_name" } ], "check_after_seconds": 30 } ``` Invalid inputs are listed in `rejected` (free); the rest run. Credits for the most the list can cost are checked **up front** (`402` if short); you pay only for what is scored. ## Check ```bash curl "https://mmkuffhlzytnmgraagbp.supabase.co/functions/v1/score/domain/bulk?batch_id=a3a4f2e6-…&page=1" -H "Authorization: Bearer $PLATINUX_API_KEY" ``` `202` while running, `200` when complete; 100 results per page. **Keep checking:** each check also moves the list forward. ```json { "batch_id": "a3a4f2e6-…", "status": "complete", "total": 3, "finished": 3, "processing": 0, "credits_charged": 20, "results": [ { "input": "notion.so", "input_type": "domain", "domain": "notion.so", "status": "complete", "score": 48, "scored_at": "…", "credits_charged": 10 }, { "input": "https://www.notion.so/pricing", "input_type": "domain", "domain": "notion.so", "status": "complete", "score": 48, "scored_at": "…", "credits_charged": 0 }, { "input": "linear.app", "input_type": "domain", "domain": "linear.app", "status": "complete", "score": 48, "scored_at": "…", "credits_charged": 10 } ], "page": 1, "pages": 1 } ``` **One score per company:** inputs that lead to the same company share one score, charged once. ## Result status | `status` | Meaning | Charged | |---|---|---| | `processing` | Still working | | | `complete` / `partial` | Scored (`partial`: some data didn't arrive in time) | The input's price, once per company | | `not_found` | No company found (email or LinkedIn) | No | | `temporary_email` | A disposable email | No | | `rejected` | The company's website failed the [Domain checks](/domain-checks); `reason` says why | No | | `insufficient_credits` | Ran out of credits | No | | `failed` | A data source kept failing | No | ## Good to know - **One list at a time per account** (shared with every bulk scoring endpoint): `409 batch_in_progress`. - **Timing:** domains and work emails go at the speed of scoring (usually a few minutes); generic emails and LinkedIn URLs add a few seconds each to find the company. ## Errors | HTTP | `error` | When | |---|---|---| | 400 | `invalid_input` | Missing `template_id` / `inputs`, or nothing valid (`reason: none_valid`) | | 400 | `too_many_inputs` | More than 1,000 | | 401 | `unauthorized` | Missing, wrong or revoked key | | 402 | `insufficient_credits` | Balance below the most the list can cost | | 404 | `batch_not_found` | Wrong `batch_id` | | 409 | `batch_in_progress` | A scoring list is already running | | 409 / 422 | `template_not_live` / `template_empty` | Template problems | --- # Company details > Name, industry, size, revenue range, location and more for one company domain. `POST https://mmkuffhlzytnmgraagbp.supabase.co/functions/v1/api-company` ## Request ```bash curl -X POST "https://mmkuffhlzytnmgraagbp.supabase.co/functions/v1/api-company" \ -H "Authorization: Bearer $PLATINUX_API_KEY" -H "Content-Type: application/json" \ -d '{"domain": "stripe.com"}' ``` | Body field | Type | Required | Notes | |---|---|---|---| | `domain` | string | Yes | The company's website. `https://www.stripe.com/about` is cleaned to `stripe.com` | ## Found: `200`, 1 credit ```json { "status": "found", "domain": "stripe.com", "company": { "name": "Stripe", "website": "https://stripe.com", "description": "…", "slogan": "…", "industry": "Technology, Information and Internet", "specialties": [], "company_type": "Privately Held", "employee_count": 14127, "headcount_range": "5001-10000", "employee_growth": [], "revenue_range": { "estimatedMinRevenue": { "amount": 500, "unit": "MILLION", "currency": "USD" }, "estimatedMaxRevenue": { "amount": 1, "unit": "BILLION", "currency": "USD" } }, "founded_year": 2010, "location": { "streetAddress": "…", "addressLocality": "South San Francisco", "addressRegion": "California", "postalCode": "…", "addressCountry": "United States of America", "addressCountryCode": "US" }, "phone": null, "logo_url": "https://…", "linkedin_url": "https://www.linkedin.com/company/stripe/", "linkedin_id": "stripe" }, "domain_match": true, "source": "icypeas", "fetched_at": "2026-11-19T17:23:33Z", "cached": false, "credits_charged": 1 } ``` ## Found again within 30 days: `200`, free The same body with `"cached": true` and `"credits_charged": 0`. ## Not found: `200`, free ```json { "status": "not_found", "domain": "nonexistent-xyz-123.com", "company": null, "domain_match": null, "source": "icypeas", "fetched_at": "2026-11-19T18:21:40Z", "cached": false, "credits_charged": 0 } ``` ## Fields | Field | Meaning | |---|---| | `status` | `found` or `not_found` | | `company` | The company, or `null` when not found. **Any field inside can be `null`**; `employee_growth` is often empty | | `company.headcount_range` | Text, for example `"51-200"` | | `company.revenue_range` | Estimated minimum and maximum revenue, each with `amount`, `unit` and `currency` | | `company.location` | Head office address, as an object | | `domain_match` | `false` when the company's listed website isn't exactly the domain you sent but the company matches (for example Google lists `goo.gle`). These matches are correct | | `source` | Where the data came from | | `fetched_at` | When the data was fetched | | `cached` | `true` when the answer came from a lookup in the last 30 days | | `credits_charged` | 1 for a new company found, otherwise 0 | **Large brands may return a division:** a domain shared by several company pages returns the page linked to that domain (for example `amazon.com` returns Amazon Web Services). ## Errors | HTTP | `error` | When | |---|---|---| | 400 | `invalid_input` | Body isn't JSON, or `domain` is missing | | 400 | `invalid_domain` | A page on another site (for example a LinkedIn or Facebook link), not a company website | | 401 | `unauthorized` | Missing, wrong or revoked key | | 402 | `insufficient_credits` | No credits left | | 502 | `provider_unavailable` | The data source didn't answer. Nothing was charged; try again | --- # Company details in bulk > Company details for up to 1,000 domains in one call. `POST https://mmkuffhlzytnmgraagbp.supabase.co/functions/v1/api-company-bulk` ## Request ```bash curl -X POST "https://mmkuffhlzytnmgraagbp.supabase.co/functions/v1/api-company-bulk" \ -H "Authorization: Bearer $PLATINUX_API_KEY" -H "Content-Type: application/json" \ -d '{"domains": ["miro.com", "loom.com", "airtable.com"]}' ``` | Body field | Type | Required | Notes | |---|---|---|---| | `domains` | array of strings | Yes | 1 to 1,000 domains | How it answers depends on the size of the list: | Domains | Answer | |---|---| | **Up to 100** | Results straight away, `200` | | **101 to 1,000** | `202` with a `batch_id`; collect the results with `GET`. Usually ready within a minute | ## Up to 100 domains: `200` ```json { "status": "complete", "total": 3, "found": 3, "not_found": 0, "credits_charged": 2, "rejected": [], "results": [ { "domain": "miro.com", "status": "found", "company": { "name": "Miro", "…": "…" }, "domain_match": true, "cached": false, "credits_charged": 1 }, { "domain": "loom.com", "status": "found", "company": { "name": "Loom", "…": "…" }, "domain_match": true, "cached": false, "credits_charged": 1 }, { "domain": "airtable.com", "status": "found", "company": { "name": "Airtable", "…": "…" }, "domain_match": true, "cached": true, "credits_charged": 0 } ] } ``` Each `company` has the same fields as [`api-company`](/company). A not-found item: ```json { "domain": "zz-unknown.com", "status": "not_found", "company": null, "domain_match": null, "cached": false, "credits_charged": 0 } ``` ## 101 to 1,000 domains ### Started: `202` ```json { "status": "processing", "batch_id": "7c2f…", "total": 640, "rejected": [ { "domain": "x.com/acme", "reason": "invalid_domain" } ], "check_after_seconds": 30 } ``` ### Check ```bash curl "https://mmkuffhlzytnmgraagbp.supabase.co/functions/v1/api-company-bulk?batch_id=7c2f…&page=1" -H "Authorization: Bearer $PLATINUX_API_KEY" ``` Still running, `202`: ```json { "status": "processing", "batch_id": "7c2f…", "total": 640 } ``` Done, `200`, 100 results per page: ```json { "status": "complete", "batch_id": "7c2f…", "total": 640, "found": 598, "not_found": 42, "credits_charged": 571, "results": [ { "domain": "…", "status": "found", "…": "…" } ], "page": 1, "pages": 7 } ``` Failed (data source down), `200`, nothing charged: ```json { "status": "failed", "batch_id": "7c2f…", "total": 640, "error": "provider_unavailable", "message": "nothing was charged; start again" } ``` ## Credits 1 credit per company found. Cached (looked up in the last 30 days) and not-found domains are free. Credits are checked up front for the domains not in the cache. ## Errors | HTTP | `error` | When | |---|---|---| | 400 | `invalid_input` | `domains` missing or empty | | 400 | `invalid_domain` | No usable domain in the list | | 400 | `too_many_domains` | More than 1,000 domains | | 401 | `unauthorized` | Missing, wrong or revoked key | | 402 | `insufficient_credits` | Not enough credits for the domains not in the cache | | 404 | `batch_not_found` | Wrong `batch_id`, or another account's batch | | 502 | `provider_unavailable` | The data source didn't answer. Nothing was charged | --- # Email to company domain > Find the domain of the company a person works at, from their email address. `POST https://mmkuffhlzytnmgraagbp.supabase.co/functions/v1/api-email-domain` Send an email address and get back the **domain of the company the person works at**. ## Request ```bash curl -X POST "https://mmkuffhlzytnmgraagbp.supabase.co/functions/v1/api-email-domain" \ -H "Authorization: Bearer $PLATINUX_API_KEY" -H "Content-Type: application/json" \ -d '{"email": "jane.doe@gmail.com"}' ``` | Body field | Type | Required | Notes | |---|---|---|---| | `email` | string | Yes | Any email address. Case and spaces don't matter | ## How the email is handled | Email type | Example | What you get | Credits | |---|---|---|---| | **Work** | `priya@mail.acme.com` | The email's own domain, cleaned to the main domain: `acme.com` | **0** | | **Temporary** | `someone@mailinator.com` | No domain, with a message | **0** | | **Generic** (Gmail, Outlook, etc.) | `jane.doe@gmail.com` | We find the person's professional profile, take their **current** employer and return its website domain | **10**, only when found | Generic email providers (Gmail, Outlook, Yahoo, iCloud, Proton and about 380 domains in all) and temporary-mail services (about 160) are recognised from built-in lists. Every other domain is treated as a work email. ## Responses **Work email, `200`, free** ```json { "status": "found", "type": "work", "email": "lee@team.hubspot.com", "domain": "hubspot.com", "credits_charged": 0 } ``` **Generic email, company found, `200`, 10 credits** ```json { "status": "found", "type": "personal", "email": "jane.doe@gmail.com", "domain": "acme.com", "cached": false, "credits_charged": 10 } ``` **Generic email, asked again within 30 days, `200`, free** ```json { "status": "found", "type": "personal", "email": "jane.doe@gmail.com", "domain": "acme.com", "cached": true, "credits_charged": 0 } ``` **Generic email, nothing found, `200`, free** ```json { "status": "not_found", "type": "personal", "email": "someone@yahoo.co.in", "domain": null, "credits_charged": 0 } ``` **Temporary email, `200`, free** ```json { "status": "temporary_email", "type": "temporary", "email": "someone@mailinator.com", "domain": null, "credits_charged": 0, "message": "This is a temporary (disposable) email address, so there is no company domain." } ``` ## Fields | Field | Meaning | |---|---| | `status` | `found`, `not_found` or `temporary_email` | | `type` | `work`, `personal` (a generic email such as Gmail or Outlook) or `temporary` | | `domain` | The company's main domain (`news.acme.com` becomes `acme.com`; endings like `acme.co.uk` are kept), or `null` | | `cached` | Generic emails only: `true` when the answer came from a lookup in the last 30 days (7 days for not found) | | `message` | Temporary emails only | | `credits_charged` | 0 or 10 | ## Good to know - **Several current jobs:** the main one listed on the person's profile is used. - **No website listed** for the employer: returned as `not_found`, free. - **Speed:** work and temporary emails answer at once; generic emails take a few seconds. ## Errors | HTTP | `error` | When | |---|---|---| | 400 | `invalid_email` | Not a valid email address | | 401 | `unauthorized` | Missing, wrong or revoked key | | 402 | `insufficient_credits` | A generic email needs 10 credits available | | 405 | `method_not_allowed` | Use `POST` | | 502 | `provider_unavailable` | A data source didn't answer. Nothing was charged; try again | --- # Email to company domain in bulk > Send up to 1,000 email addresses and get the company domain for each, without scoring. `POST https://mmkuffhlzytnmgraagbp.supabase.co/functions/v1/api-email-domain-bulk` The list version of [Email to company domain](/email-domain), with the same rules and prices. ## Request ```bash curl -X POST "https://mmkuffhlzytnmgraagbp.supabase.co/functions/v1/api-email-domain-bulk" \ -H "Authorization: Bearer $PLATINUX_API_KEY" -H "Content-Type: application/json" \ -d '{"emails": ["priya@mail.stripe.com", "jane.doe@gmail.com", "x@mailinator.com", "not-an-email"]}' ``` | Body field | Type | Required | Notes | |---|---|---|---| | `emails` | array of strings | Yes | 1 to 1,000. Duplicates are merged (case doesn't matter) | Work emails, temporary emails and generic emails looked up in the last 30 days are answered at once. New generic emails are looked up in the background. ## Everything answered at once: `200` ```json { "status": "complete", "total": 3, "found": 2, "not_found": 0, "temporary": 1, "credits_charged": 0, "rejected": [ { "email": "not-an-email", "reason": "invalid_email" } ], "results": [ { "email": "priya@mail.stripe.com", "type": "work", "status": "found", "domain": "stripe.com", "credits_charged": 0 }, { "email": "jane.doe@gmail.com", "type": "personal", "status": "found", "domain": "acme.com", "cached": true, "credits_charged": 0 }, { "email": "x@mailinator.com", "type": "temporary", "status": "temporary_email", "domain": null, "credits_charged": 0, "message": "This is a temporary (disposable) email address, so there is no company domain." } ] } ``` ## New generic emails to look up: `202` ```json { "status": "processing", "batch_id": "481c589e-…", "total": 3, "pending": 2, "rejected": [], "check_after_seconds": 15 } ``` Then check every `check_after_seconds` until `status` is `complete`. Each check also moves the lookups along. ```bash curl "https://mmkuffhlzytnmgraagbp.supabase.co/functions/v1/api-email-domain-bulk?batch_id=481c589e-…&page=1" -H "Authorization: Bearer $PLATINUX_API_KEY" ``` ```json { "status": "complete", "batch_id": "481c589e-…", "total": 3, "finished": 3, "processing": 0, "found": 2, "not_found": 1, "credits_charged": 10, "results": [ { "email": "jane.doe@gmail.com", "type": "personal", "status": "found", "domain": "acme.com", "cached": false, "credits_charged": 10 }, { "email": "someone@gmail.com", "type": "personal", "status": "not_found", "domain": null, "cached": false, "credits_charged": 0 }, { "email": "lee@asana.com", "type": "work", "status": "found", "domain": "asana.com", "credits_charged": 0 } ], "page": 1, "pages": 1 } ``` `202` while running, `200` when complete. 100 results per page. ## Result fields | Field | Values | |---|---| | `type` | `work` · `personal` (a generic email such as Gmail or Outlook) · `temporary` | | `status` | `processing` · `found` · `not_found` · `temporary_email` · `failed` (a data source kept failing; free) · `insufficient_credits` | | `domain` | The company's main domain, or `null` | | `cached` | Generic emails only: `true` when the answer came from a lookup in the last 30 days | | `credits_charged` | 10 for a new generic email that was found, otherwise 0 | ## Credits **10 per generic email newly found.** Work, temporary, not-found and recently looked-up emails are free. Credits for every new generic email are checked up front; if the balance is short, nothing starts (`402`). ## Errors | HTTP | `error` | When | |---|---|---| | 400 | `invalid_input` | `emails` missing or empty, or none valid (`reason: none_valid`) | | 400 | `too_many_emails` | More than 1,000 emails | | 401 | `unauthorized` | Missing, wrong or revoked key | | 402 | `insufficient_credits` | Balance below the most the lookup can cost | | 404 | `batch_not_found` | Wrong `batch_id`, or another account's batch | --- # Errors > Every error code, what it means and what to do. Errors use normal HTTP status codes and always have the same JSON shape: an `error` code you can switch on, and usually a short `message`. ```json { "error": "insufficient_credits", "message": "this score costs 10 credits" } ``` Invalid domains also carry a one-word `reason` (see [Domain checks](/domain-checks)): ```json { "error": "invalid_domain", "reason": "file_name" } ``` **Switch on `error` (and `reason`), not on `message`.** Messages are for people and may change. ## All error codes | HTTP | `error` | Endpoints | What to do | |---|---|---|---| | 400 | `invalid_input` | All | Fix the field named in `message` (or send valid JSON) | | 400 | `invalid_domain` | Scoring, company | Send the company's own website. `reason` says what was wrong | | 400 | `invalid_email` | `/score/email`, email → domain | Send a valid email address | | 400 | `invalid_url` | `/score/social` | Send a LinkedIn company or person URL (`reason: not_linkedin`) | | 400 | `too_many_inputs` | `/score/…/bulk` | Send at most 1,000 inputs per call | | 400 | `too_many_domains` | Bulk | Send at most 1,000 domains per call | | 400 | `too_many_emails` | Email bulk | Send at most 1,000 emails per call | | 401 | `unauthorized` | All | Send a valid key: `Authorization: Bearer plx_live_…` | | 402 | `insufficient_credits` | Scoring, company, email → domain | Top up credits in the app | | 403 | `template_not_allowed` | Scoring | Use one of your own templates | | 404 | `job_not_found` | Score | Check `job_id`. Jobs are visible only to the account that started them | | 404 | `batch_not_found` | Bulk | Check `batch_id` | | 404 | `not_found` | `/score/…` | Unknown path: use `/score/domain`, `/score/email` or `/score/social` | | 405 | `method_not_allowed` | All | Use the method shown in the reference | | 409 | `template_not_live` | Scoring | Use the template with `is_live: true` | | 409 | `batch_in_progress` | Bulk scoring | Wait for your running batch to finish | | 422 | `template_empty` | Scoring | Switch on at least one signal in your live template | | 500 | `internal_error` | All | Something failed on our side. Try again | | 502 | `provider_unavailable` | Company, email → domain | A data source didn't answer. Try again; nothing was charged | ## Retrying - **Safe to retry:** `500`, `502`, and network errors. Wait a few seconds, then back off. - **Don't retry unchanged:** `400`, `401`, `403`, `404`, `422`. The same request will fail the same way. - **Retry later:** `402` after topping up; `409 batch_in_progress` after the running batch completes. - **Scoring is safe to repeat:** sending the same domain again returns the running or recent job instead of charging twice. --- # Domain checks > How scoring screens every domain, and the one-word reason returned for each kind of rejected input. Before anything is scored or charged, every company domain is screened, whether you send it to [`/score/domain`](/score-domain) or we find it from an [email](/score-email) or [LinkedIn URL](/score-social). Inputs that aren't a company's own website are rejected with HTTP `400` and **a one-word `reason`** you can switch on in code: ```json { "error": "invalid_domain", "reason": "social_media" } ``` In a bulk call, each rejected domain is listed in `rejected` with its reason, and the rest are still scored: ```json { "rejected": [ { "domain": "logo.png", "reason": "file_name" } ] } ``` **Rejected domains are never charged.** ## Reasons ### Instant checks | `reason` | Rejected input | Examples | |---|---|---| | `empty` | Nothing entered | `""`, `" "` | | `invalid_format` | Not shaped like a domain | `acme`, `hello world.com`, `-bad-.com` | | `invalid_tld` | The ending isn't a real domain ending | `acme.con`, `acme.comm` | | `email` | An email address | `jane@acme.com` | | `ip_address` | An IP address, with or without a port or path | `192.168.1.1`, `http://10.0.0.1:8080/x`, `2001:db8::1` | | `file_name` | A file name or path | `logo.png`, `Document.pdf`, `Presentation.pptx`, `C:\files\deck.pptx` | | `social_media` | A social network | `linkedin.com/company/acme`, `instagram.com/acme`, `facebook.com`, `x.com`, `youtube.com` | | `messaging` | A chat or meeting link | `wa.me/9198…`, `chat.whatsapp.com/…`, `t.me/acme`, `discord.gg/…` | | `common_site` | A well-known site, not a prospect | `google.com`, `google.co.in`, `wikipedia.org`, `chatgpt.com`, `example.com` | | `email_provider` | A generic or temporary email service | `gmail.com`, `outlook.com`, `mailinator.com` | | `link_shortener` | A short-link or link-in-bio service | `bit.ly/x`, `tinyurl.com/x`, `linktr.ee/acme` | | `marketplace` | A marketplace, directory or app store | `indiamart.com`, `amazon.de`, `crunchbase.com`, `play.google.com` | | `free_host` | A free website on a hosting or site-builder domain | `acme.myshopify.com`, `acme.wixsite.com`, `acme.vercel.app` | ### Live checks These look at the domain on the internet before scoring. | `reason` | Rejected input | |---|---| | `unregistered` | The domain doesn't exist: expired or never registered | | `no_website` | Registered, but no website answers, the page is blank, or it shows a default server page | | `parked` | Parked or for sale (redirects to a domain marketplace, or a "this domain is for sale" page) | | `coming_soon` | A "Coming soon" or "Under construction" page | ### Bulk only | `reason` | Meaning | |---|---| | `already_processing` | A single scoring job for this domain is already running | | `none_valid` | Whole call: no domain in the list passed the checks | ## How the checks work - **Cleaning first:** `https://www.Acme.com/about?x=1` is checked as `acme.com`. Paths and `www.` are fine. - **Subdomains count:** `in.linkedin.com`, `m.facebook.com` and `x.tradeindia.com` are recognised as their parent site. - **Real endings only:** the domain ending is checked against the official list of every top-level domain. - **File names vs. domains:** endings that are both a file type and a real domain ending, such as `.ai` and `.app`, are treated as domains, so `x.ai` passes. - **Live checks never block a real company by accident:** a slow site, a site behind bot protection, or a site with a temporary server error is **accepted**. A domain is rejected only on clear evidence. ## Handling reasons in code ```javascript const res = await fetch(`${BASE}/score/domain`, { method: "POST", headers, body: JSON.stringify({ domain, template_id }) }); const body = await res.json(); if (res.status === 400 && body.error === "invalid_domain") { switch (body.reason) { case "social_media": case "messaging": return "That's a social or chat link. Enter the company's website."; case "file_name": return "That looks like a file name."; case "unregistered": case "no_website": return "This domain has no website."; case "parked": return "This domain is parked or for sale."; case "coming_soon": return "This website isn't live yet."; default: return "Enter the company's own website, like acme.com."; } } ``` --- # Status values > Every value the status field can take, per endpoint. | Endpoint | `status` values | |---|---| | [`/score/domain`, `/email`, `/social`](/score-domain) | `processing` · `complete` · `partial` · `not_found` · `temporary_email` | | [`/score/…/bulk`](/score-list), each result | as above, plus `rejected` · `insufficient_credits` · `failed` | | [`api-company`](/company) | `found` · `not_found` | | [`api-company-bulk`](/company-bulk), batch | `processing` · `complete` · `failed` | | [`api-company-bulk`](/company-bulk), each result | `found` · `not_found` | | [`api-email-domain`](/email-domain) | `found` · `not_found` · `temporary_email` | | [`api-email-domain-bulk`](/email-domain-bulk), each result | `processing` · `found` · `not_found` · `temporary_email` · `failed` · `insufficient_credits` | ## Meanings | Value | Meaning | |---|---| | `processing` | Still running. Check again after `check_after_seconds` | | `complete` | Finished with all data | | `partial` | Finished, but some data didn't arrive in time. The score uses what arrived | | `found` / `not_found` | Whether a company or domain was found | | `failed` | A company batch couldn't run. Nothing was charged; start it again | | `temporary_email` | A disposable email address; there's no company to find | ## HTTP codes for successful calls | HTTP | Meaning | |---|---| | `200` | Done: the answer is in the body | | `202` | Accepted and running: check back later | --- # Limits > Current limits of version 1 of the API. | Limit | Value | |---|---| | Domains per bulk call | **1,000** | | Emails per bulk call | **1,000** | | Running score batches per account | **1** at a time | | Active API keys per account | **5** | | Bulk results per page | **100** | | Free re-use of a company-details or email lookup | **30 days** | | Re-use of a score | **None**: every run is scored and charged | | Inputs per bulk scoring call | **1,000** | | Scoring template | Your **live** template only (the one with `is_live: true`) | ## Coming later - Scoring with any of your templates, not just the live one. - Webhooks when a score or batch is finished (for now, check with `GET`). - Per-key rate limits and read-only keys. ## Versioning This is **version 1**. Changes that could break your code (removing or renaming fields) will come as a new version. New fields may be added to responses at any time, so ignore fields you don't know. --- # FAQ > Short answers to common questions about the Platinux API. ## Getting started ### How do I get an API key? Sign in at [platinux.net/dashboard/score](https://platinux.net/dashboard/score) and create a key. It is shown only once, so copy it straight away. See [Authentication](/authentication). ### What do I need before I can score? A template. Call [`GET api-templates`](/templates) and use the `template_id` with `"is_live": true`. Every scoring call needs it. ### What is a template? The set of buying signals that count towards a score. You create and edit templates in the Platinux app. The API only lists them. ## Scores ### What does the score mean? A number from 0 to 100. Higher means the company is showing stronger buying signals for what your template looks for. ### Is the score about the person or the company? The company. When you send an email or a person's LinkedIn profile, we find their current company and score that. ### How long does a score take? Usually 1 to 3 minutes. Scoring runs in the background: you get a `job_id` (or a `batch_id` for a list) and check back after `check_after_seconds`. ### Why is my result `partial`? Some data didn't arrive in time. The score uses what did arrive. See [Status values](/status-values). ## Credits ### What does a score cost? 10 credits for a domain, LinkedIn URL, or company or work email. 20 for a generic email (Gmail, Outlook, etc.). Full table in [Credits](/credits). ### Am I charged when nothing is scored? No. Invalid inputs, temporary emails, companies we can't find and rejected websites all cost 0. ### Is a score reused if I send the same company again? No. Every run is scored and charged again. Within one list, inputs that lead to the same company are charged once. ### What happens when I run out of credits? Scoring calls return `402 insufficient_credits`. Top up in the app and try again. ## Limits and errors ### How many companies can I score at once? Up to 1,000 inputs per bulk call, with one scoring list running at a time per account. See [Limits](/limits). ### Can I score with a template that isn't live? Not yet. Scoring uses your live template only. ### Which errors are safe to retry? `500`, `502` and network errors. See [Errors](/errors) for every code.