{ "openapi": "3.0.3", "info": { "title": "StatementIQ Developer API", "version": "1.0.0", "description": "StatementIQ is a merchant-acquiring and payments intelligence platform. This is the supported, externally published API for integrators.\n\n## What this API is\n\nA **read-only** view of canonical entities, the organizations that represent them, the relationships between them, and the reference vocabularies used to classify them. Every operation is a `GET`.\n\n## What this API is not\n\nStatementIQ's internal surface is considerably larger and includes administrative, job-control, diagnostic and security-management operations. Those are deliberately **not** part of this contract, are not supported for external use, and may change without notice. Their absence here is a product decision, not an oversight.\n\n## Authentication\n\nEvery operation except `GET /health` requires a **registered API client credential**, sent as an HTTP bearer token:\n\n```\nAuthorization: Bearer \n```\n\nCredentials are issued to you by StatementIQ; there is no self-service registration. Treat the credential as a secret: it is equivalent to a password, it is not scoped to a single IP, and StatementIQ stores only a SHA-256 hash of it, so a lost credential cannot be recovered and must be reissued.\n\nHuman login sessions and StatementIQ's internal platform credential also exist, but they are **not** part of the external integration model and are not documented here. Do not attempt to authenticate with them.\n\n## Authorization is separate from authentication\n\nAuthenticating proves *who* you are. What you can *see* is decided separately, by the organization grants attached to your API client.\n\n- **401** means the credential is missing, malformed, unknown, or no longer valid.\n- **403** means the credential is valid but is not permitted to perform the operation.\n\nList operations do **not** return 403 for records you cannot see. They return `200` with those records filtered out, so an empty page can mean either \"nothing matches\" or \"nothing you can see matches\". Single-record lookups return `404` rather than `403` where confirming existence would itself disclose something.\n\n## Hosts\n\n**The API base URL for this document is the `servers` entry above.** Send every call there.\n\nStatementIQ runs two environments:\n\n| | Host | Credentials |\n|---|---|---|\n| Sandbox | `dev-api.stmtiq.com` | Issued for sandbox use only |\n| Production | `api.stmtiq.com` | Issued separately, on approval |\n\n**A sandbox credential does not work in production, and the reverse is also true.** Each environment issues its own, and access to production is granted separately. Develop against the sandbox; ask StatementIQ when you are ready for production.\n\nDocumentation is published separately from the API and answers no API request — never send calls to the documentation host.\n\n## Paths\n\nSend paths exactly as written here, against the server URL. Do not add an `/api` prefix; StatementIQ's load balancer adds it internally, and the `path` field inside error bodies shows that internal form.\n\n## Versioning\n\nThis contract is versioned independently of StatementIQ's internal release identifiers, following semantic versioning. `1.0.0` is the first published contract. Additive changes (new optional fields, new operations) increment the minor version; breaking changes increment the major version and will be announced before release.\n\n## Rate limits and stability\n\nNo rate limit is currently enforced. That is not a guarantee: build clients that tolerate `429` and `503` even though this contract does not yet document them as expected responses.", "contact": { "name": "StatementIQ API Support", "url": "https://www.statementiq.com" } }, "servers": [ { "url": "https://dev-api.stmtiq.com", "description": "Sandbox API. Unstable data; sandbox credentials only." } ], "security": [ { "apiClientBearer": [] } ], "tags": [ { "name": "Entities", "description": "Canonical organizations and people as StatementIQ understands them. An entity is a real-world organization, not a registration record: a single company with three Visa service-provider registrations is one entity." }, { "name": "Relationships", "description": "Directed, evidence-backed links between entities — sponsorship, processing, registration and similar." }, { "name": "Organizations", "description": "The tenancy and access-control view of an entity. An organization is how StatementIQ scopes who may see what; it may reference the entity it represents." }, { "name": "Sponsor Banks", "description": "Entities acting in a sponsor-bank capacity, and their relationships." }, { "name": "Reference Data", "description": "Stable vocabularies used by the other resources: classification types and relationship role types." }, { "name": "Service", "description": "Service liveness." } ], "paths": { "/health": { "get": { "operationId": "getHealth", "tags": [ "Service" ], "summary": "Check service liveness", "description": "Returns the service's liveness status. This is the only operation in this contract that does not require a credential, so it is also the quickest way to confirm that your network path to StatementIQ works before you start debugging authentication.\n\nIt reports only that the application is serving requests. It does not report database health, dependency health, or whether your credential is valid.", "security": [], "responses": { "200": { "description": "The service is serving requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" }, "example": { "application": "StatementIQ", "status": "UP", "timestamp": "2026-09-11T14:44:56.199Z" } } } } } } }, "/entities": { "get": { "operationId": "listEntities", "tags": [ "Entities" ], "summary": "Search and list entities", "description": "Returns a page of canonical entities your credential is permitted to see.\n\nResults are filtered to your organization grants. Entities you cannot see are omitted rather than refused, so an empty page does not distinguish \"no match\" from \"no access\". A page beyond the end returns empty `content` with the true totals rather than an error.", "parameters": [ { "$ref": "#/components/parameters/Search" }, { "name": "classification", "in": "query", "required": false, "description": "Filter to entities carrying this classification code. Codes come from `GET /entity-classification-types`. May be repeated to filter on several classifications; combine with `classificationMatch` to choose the combination rule.", "schema": { "type": "string" }, "example": "ACQUIRER" }, { "name": "classificationMatch", "in": "query", "required": false, "description": "How multiple `classification` values combine. `ANY` returns entities carrying at least one; `ALL` returns only entities carrying every one. Defaults to `ANY`.", "schema": { "type": "string", "enum": [ "ANY", "ALL" ] } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Size" } ], "responses": { "200": { "description": "A page of entities. May be empty.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityPage" }, "example": { "content": [ { "id": "3f1c8a52-9d64-4a1e-9c77-2b0f5ad41e90", "name": "EXAMPLE PAYMENTS LLC", "status": "ACTIVE", "website": "https://example.invalid", "createdAt": "2026-01-15T09:12:44.512Z", "updatedAt": "2026-08-02T17:41:03.118Z" } ], "number": 0, "size": 25, "totalElements": 1, "totalPages": 1, "first": true, "last": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/entities/{id}": { "get": { "operationId": "getEntity", "tags": [ "Entities" ], "summary": "Retrieve one entity", "description": "Returns a single canonical entity by its UUID.\n\nIf the entity has been merged into another entity, StatementIQ resolves to the surviving entity, so the `id` in the response may differ from the one you requested. That is deliberate: the losing UUID stays valid as a permanent alias rather than breaking.", "parameters": [ { "$ref": "#/components/parameters/EntityId" } ], "responses": { "200": { "description": "The entity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entity" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/entities/{id}/relationships": { "get": { "operationId": "listEntityRelationships", "tags": [ "Relationships" ], "summary": "List an entity's relationships", "description": "Returns every relationship attached to the entity, in both directions, with the counterparty summarised inline.\n\n`direction` is relative to the entity you asked about: `OUTBOUND` means this entity is the source of the relationship, `INBOUND` means it is the target. Superseded relationships are not returned.", "parameters": [ { "$ref": "#/components/parameters/EntityId" } ], "responses": { "200": { "description": "The entity's relationships. May be empty.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Relationship" } }, "example": [ { "relationshipId": "b7e2d1a0-4c93-4f8e-8a21-6d5c0e9f3a44", "direction": "OUTBOUND", "relationshipType": "SPONSORED_BY", "status": "ACTIVE", "confidence": "VERIFIED", "directness": "DIRECT", "commercialStatus": "ACTIVE", "effectiveFrom": "2024-03-01", "effectiveTo": null, "counterpartyId": "c19f7b34-2e55-4d10-9f6a-81b3c7d2e005", "counterpartyName": "EXAMPLE SPONSOR BANK, N.A.", "counterpartyStatus": "ACTIVE" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/organizations": { "get": { "operationId": "listOrganizations", "tags": [ "Organizations" ], "summary": "List organizations", "description": "Returns a page of organizations your credential is permitted to see.\n\nAs with entities, organizations outside your grants are filtered out rather than refused.", "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Size" } ], "responses": { "200": { "description": "A page of organizations. May be empty.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/organizations/{id}": { "get": { "operationId": "getOrganization", "tags": [ "Organizations" ], "summary": "Retrieve one organization", "description": "Returns a single organization by its UUID. `entityId` links to the canonical entity this organization represents, and is `null` where no entity has been linked.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The organization's UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/organization-relationships": { "get": { "operationId": "listOrganizationRelationships", "tags": [ "Relationships" ], "summary": "List organization relationships", "description": "Returns relationships expressed between organizations rather than between canonical entities. Use this where you need the tenancy view; use `GET /entities/{id}/relationships` where you need the intelligence view.", "responses": { "200": { "description": "Organization relationships. May be empty.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Relationship" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/banks": { "get": { "operationId": "listSponsorBanks", "tags": [ "Sponsor Banks" ], "summary": "Search and list sponsor banks", "description": "Returns a page of entities acting in a sponsor-bank capacity. The response shape is identical to `GET /entities`: a sponsor bank is an entity, filtered by its role rather than modelled as a separate type.", "parameters": [ { "$ref": "#/components/parameters/Search" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Size" } ], "responses": { "200": { "description": "A page of sponsor-bank entities. May be empty.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/banks/{id}": { "get": { "operationId": "getSponsorBank", "tags": [ "Sponsor Banks" ], "summary": "Retrieve one sponsor bank", "description": "Returns a single sponsor-bank entity by its UUID.", "parameters": [ { "$ref": "#/components/parameters/EntityId" } ], "responses": { "200": { "description": "The sponsor-bank entity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entity" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/banks/{id}/relationships": { "get": { "operationId": "listSponsorBankRelationships", "tags": [ "Sponsor Banks" ], "summary": "List a sponsor bank's relationships", "description": "Returns the relationships attached to a sponsor-bank entity, in the same shape as `GET /entities/{id}/relationships`.", "parameters": [ { "$ref": "#/components/parameters/EntityId" } ], "responses": { "200": { "description": "The sponsor bank's relationships. May be empty.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Relationship" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/entity-classification-types": { "get": { "operationId": "listEntityClassificationTypes", "tags": [ "Reference Data" ], "summary": "List entity classification types", "description": "Returns the classification vocabulary used by the `classification` filter on `GET /entities`. This is a global vocabulary, not scoped to your grants.", "responses": { "200": { "description": "The classification vocabulary.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ClassificationType" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/entity-roles": { "get": { "operationId": "listEntityRoleTypes", "tags": [ "Reference Data" ], "summary": "List entity role types", "description": "Returns the distinct role types an entity may hold, as plain strings. A global vocabulary, not scoped to your grants.", "responses": { "200": { "description": "The role-type vocabulary.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "ACQUIRER", "ISO", "PAYMENT_FACILITATOR", "SPONSOR_BANK" ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } } }, "components": { "securitySchemes": { "apiClientBearer": { "type": "http", "scheme": "bearer", "description": "A registered StatementIQ API client credential, sent as `Authorization: Bearer `.\n\nIssued to you by StatementIQ; there is no self-service registration and no rotation endpoint — contact StatementIQ to reissue. Only a SHA-256 hash is stored, so a lost credential cannot be recovered.\n\nThis is the only credential type supported for external integration." } }, "parameters": { "EntityId": { "name": "id", "in": "path", "required": true, "description": "The entity's UUID. If this entity has been merged into another, the surviving entity is returned.", "schema": { "type": "string", "format": "uuid" }, "example": "3f1c8a52-9d64-4a1e-9c77-2b0f5ad41e90" }, "Search": { "name": "search", "in": "query", "required": false, "description": "Case-insensitive partial match against the entity's canonical name. Omit to list without filtering.", "schema": { "type": "string" }, "example": "example payments" }, "Page": { "name": "page", "in": "query", "required": false, "description": "Zero-based page index. Defaults to 0. A page beyond the end returns empty `content` rather than an error.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, "Size": { "name": "size", "in": "query", "required": false, "description": "Number of records per page.", "schema": { "type": "integer", "minimum": 1, "default": 20 } } }, "responses": { "BadRequest": { "description": "The request was malformed or self-contradictory — for example a non-numeric `page`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "No credential was supplied, or the credential is malformed, unknown, or no longer valid. StatementIQ does not distinguish these cases in the response, deliberately.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Missing bearer token" } } } }, "Forbidden": { "description": "The credential is valid but is not permitted to perform this operation. Note that list operations filter rather than refuse, so a 403 here means the operation itself is denied, not that individual records were hidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "No such record, or a record you are not permitted to know exists. StatementIQ returns 404 rather than 403 where confirming existence would itself disclose something.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Health": { "type": "object", "properties": { "application": { "type": "string", "description": "Always `StatementIQ`." }, "status": { "type": "string", "description": "`UP` when the service is serving requests." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server time, UTC." } } }, "Entity": { "type": "object", "description": "A canonical real-world organization or person.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Stable external identifier for the entity." }, "name": { "type": "string", "description": "The entity's canonical name as StatementIQ has resolved it, which may differ from any single source's spelling." }, "status": { "type": "string", "description": "Lifecycle state, for example `ACTIVE`, `MERGED` or `INVALID`. A `MERGED` entity is returned only when requested directly by its old identifier." }, "website": { "type": "string", "nullable": true, "description": "Best known website, or null. A populated value is a candidate that StatementIQ has recorded, not necessarily a verified official site." }, "createdAt": { "type": "string", "format": "date-time", "description": "When StatementIQ first recorded the entity, UTC." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the entity was last modified, UTC." } } }, "Organization": { "type": "object", "description": "The tenancy and access-control view of an entity.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Stable external identifier for the organization." }, "entityId": { "type": "string", "format": "uuid", "nullable": true, "description": "The canonical entity this organization represents, or null where none is linked." }, "name": { "type": "string" }, "type": { "type": "string", "description": "Organization type, for example `INTERNAL` or `PARTNER`." }, "status": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "Relationship": { "type": "object", "description": "A directed, evidence-backed link between two entities, described from the point of view of the entity you asked about.", "properties": { "relationshipId": { "type": "string", "format": "uuid" }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "`OUTBOUND` if the requested entity is the source, `INBOUND` if it is the target." }, "relationshipType": { "type": "string", "description": "The kind of link, for example `SPONSORED_BY` or `REGISTERED_WITH`." }, "status": { "type": "string", "description": "Lifecycle state of the relationship record." }, "confidence": { "type": "string", "description": "How strongly the relationship is evidenced. This is confidence that a source asserted it, not a guarantee of truth." }, "directness": { "type": "string", "description": "Whether the link is direct or inferred through an intermediary." }, "commercialStatus": { "type": "string", "nullable": true }, "effectiveFrom": { "type": "string", "format": "date", "nullable": true, "description": "Date the relationship is known to have started, or null if unknown. Null means unknown, never \"today\"." }, "effectiveTo": { "type": "string", "format": "date", "nullable": true, "description": "Date it ended, or null if still current or unknown." }, "counterpartyId": { "type": "string", "format": "uuid", "description": "The entity at the other end." }, "counterpartyName": { "type": "string" }, "counterpartyStatus": { "type": "string" } } }, "ClassificationType": { "type": "object", "description": "One classification in the global vocabulary.", "properties": { "code": { "type": "string", "description": "Stable code to pass to the `classification` filter." }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true } } }, "EntityPage": { "type": "object", "description": "A page of entities. StatementIQ returns the standard Spring page envelope; the fields below are the ones a client should rely on.", "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/Entity" } }, "number": { "type": "integer", "description": "Zero-based index of this page." }, "size": { "type": "integer", "description": "Requested page size." }, "totalElements": { "type": "integer", "format": "int64", "description": "Total records matching the query and visible to you." }, "totalPages": { "type": "integer" }, "first": { "type": "boolean" }, "last": { "type": "boolean" } } }, "OrganizationPage": { "type": "object", "description": "A page of organizations, in the same envelope as `EntityPage`.", "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/Organization" } }, "number": { "type": "integer" }, "size": { "type": "integer" }, "totalElements": { "type": "integer", "format": "int64" }, "totalPages": { "type": "integer" }, "first": { "type": "boolean" }, "last": { "type": "boolean" } } }, "Error": { "type": "object", "description": "StatementIQ returns one of two error shapes and clients should tolerate both. Most failures carry `timestamp`, `status`, `error` and `path`; validation and upload failures carry only `error`. Note that `path` shows StatementIQ's internal `/api`-prefixed path, not the path you requested.", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "status": { "type": "integer" }, "error": { "type": "string", "description": "Short reason. Present in both error shapes." }, "path": { "type": "string" } } } } } }