| Cover image | |||
|---|---|---|---|
| Search by name to find candidate entities and their IAF CE IDs. No certificates yet, and no credits spent. | POST /match-companiesNo credit consumption | /files/1w7BNwL79afv87xM3khN | |
| Look over the candidates and confirm the right entity is the one you meant. Note its IAF CE ID for the next step. | Your check, no call | /files/cWAkzXAJW4KBOzQlqTMz | |
| Pull the full certificate data for the entity you confirmed. This is the step that consumes a credit. | SINGLE verification: POST /company/{ce_id}BULK verification: POST /bulk-company-by-id | /files/YSvlFHWbXj0VYmd5iRz2 |
| Field Name | Description |
|---|---|
| Certified Entity (CE) | A company or organisation that holds one or more certifications in IAF CertSearch. It's the thing you're verifying. |
IAF CE ID ce_id | The unique ID of a Certified Entity. Matching returns it, and you reuse it for direct lookups later. Some match responses label this simply "IAF ID", it's the same value. |
Certificate ID cert_id | The unique ID of a single certificate held by an entity. Use it when you want one specific certificate rather than a whole company. |
| Credit | The billing unit. One credit is consumed each time you successfully retrieve certificate data for a confirmed match. Discovery, loose matches, and unmatched results are free. |
Match rate match_rate | How strict name matching is, from 80 (loose) to 100 (exact), in steps of 5. Default is 90. A higher rate returns fewer but more confident matches. |
Exact match exactly_matched | A match that cleared the strict threshold, confident enough to trust automatically. This is the result that consumes a credit, and the only kind that bulk retrieval returns. |
Loose match loosely_matched | A likely but not certain match. Single /company returns it so you can review it yourself, at no cost. |
| A company name only | Retrieve Company & Certificates (POST /company). It matches and returns certificates in one call, no separate match step needed. |
| A name, but only the IAF CE ID (no certificates) | Match Companies (POST /match-companies). Free discovery and disambiguation. |
| Many company names to verify | Bulk Retrieve (POST /bulk-companies). Returns only exact matches, up to 100 per request. |
| An IAF CE ID you saved earlier | Retrieve by IAF ID (GET /company/{ce_id}), or POST /bulk-company-by-id for high volume. |
| A certificate ID | Retrieve Certificate by IAF ID (GET /certificate/{cert_id}). |
| Endpoint | When to use | Consumption | What it does |
|---|---|---|---|
| Use first when you need to find candidate companies and do not yet have a ce_id. Best for search, review, and discovery flows. | ❌ No credits consumed. No certificates returned. | Searches by company name and/or identifiers. Returns up to 10 matching Certified Entity records, including their IAF CE IDs. Does not return certificates. Supports match_result_count to control result count. |
| Use when you need to verify one company and retrieve its certificates in one call. The main retrieval endpoint for single-company verification. | ✅ One credit only for exactly_matched results. loosely_matched results return for review with no credit consumed. | Matches one company by name and/or identifiers, then returns the Certified Entity record with its certificates. Applies match_rate for name-based matching. Default is 90; valid values are 80 to 100 in steps of 5. |
| Use when you need to verify many companies in one request. Best for batch verification and backfill workflows. | ✅ One credit per exactly_matched result (certificates returned). loosely_matched results return company info only and consume no credit. Skipped entries consume no credit. Max 100 companies per request. | Same matching and retrieval logic as POST /company, but accepts up to 100 companies in one request. Exact matches return the full record with certificates. Loose matches return company information only, with no certificates, so you review them and then call a retrieval endpoint for their certs. Invalid, failed, or unmatched companies are skipped. The response includes companies_request_index for correlation. |
| Use when you already know the IAF CE ID and want the latest company and certificate data without another match step. | ✅ Credits consumed on retrieval. Per-ID billing details are pending confirmation. Max 100 IDs per request. | Retrieves Certified Entity records and certificates for one or more known ce_id values. Accepts comma-separated IDs, up to 100. Does not perform name matching or use match_rate. |
| Use when you need high-volume retrieval by known ce_id values. Best for large-scale re-verification and scheduled refreshes. | ✅ Credits consumed on retrieval. Same rules as the GET variant. Max 1000 IDs per request. | Retrieves Certified Entity records and certificates for up to 1000 known IAF CE IDs in one request. Does not perform name matching. |
| Use when you need to look up a specific certificate directly and already have the cert_id. Ideal for certificate-level verification or audit where the cert ID is known (e.g. scanned from a certificate document). | ✅ Credits consumed on retrieval. Single certificate lookup per call. | Accepts a single known cert_id and returns that certificate record including its associated certified entities. No company-level matching fields (match_type, match_status) returned. |