--- updatedAt: 2026-06-02T12:53:51.000Z agentTools: projectIndex: https://docs.trustpair.com/llms.txt --- # Retrieve all company account checks Retrieves a list of company account checks associated with the authenticated customer. This endpoint allows you to: - Filter company account checks by state, IDs, and last update date - Paginate results using cursor-based pagination **Required permissions:** - `company_account_checks_read` # OpenAPI definition ```json { "openapi": "3.0.1", "info": { "title": "TRUSTPAIR API", "version": "v1", "description": "The Trustpair API is organized around REST. Our API has predictable resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.\n\n# Definitions\nThe following API documentation is divided into different definitions. Switch between definitions using the select located at the top right of the page.\n\n# Authentication\n\nThe Trustpair API uses token to authenticate requests.\n\nThe Bearer authentication token must be provided with the request as a header: `Authorization: Bearer `\n\nAll API requests must be made over `HTTPS`. Calls made over plain `HTTP` will fail.\n\nAPI requests without authentication will also fail.\n\n\n### Error response\n\nReturns a `401 UNAUTHORIZED` code if the provided bearer token is not found.\n\n# Rate limits\nLimits are placed on the number of requests that can be made on the Trustpair API (the currently enforced limit being 100 requests over a 10 seconds periods). These limits help us provide the reliable and scalable API that our customers rely on.\n\nIf the defined limit is exceeded, the API will return an HTTP code `429 Too Many Requests`.\n\n\n# Pagination\n\nThe API returns paginated results for list endpoints. By default, the number of items returned is 10.\n\nTrustpair utilizes cursor-based pagination via the `starting_after` and `ending_before` parameters.\nBoth parameters take an existing object ID value and return objects in reverse chronological order.\nThe `ending_before` parameter returns objects listed before the named object. The `starting_after` parameter returns objects listed after the named object.\nIf both parameters are provided, only `ending_before` is used.\n\n\n| Arguments | Description | Required | Example |\n| ------------- |:-------------: | -----: | ---: |\n| limit | A limit on the number of objects to be returned, between 1 and 100. | optional, default is 10 | */?limit=2 |\n| starting_after | A cursor for use in pagination | optional | */?starting_after=c58ac778-67b5-4f98-ba33-a1e9aaf394eb |\n| ending_before | A cursor for use in pagination | optional | */?ending_before=c58ac778-67b5-4f98-ba33-a1e9aaf394eb |\n\n\n# Filters\n\nThe API results can be filtered according to different criteria on every endpoint.\n\nThere is no theoric limit on how many different elements can be submitted in a filter, only that the request header should be kept under 8kb.\n\n| Arguments | Description | Example |\n| ------------- |:-------------: | ---------------------------------------: |\n| ids | Returns selected objects | /api/v1/paid_payments?ids=a414df38-f13b-48b6-95f7-f941ca121f28,a414df38-f13b-48b6-95f7-f941ca121f29 |\n| recents | Returns objects evaluated in the last 24 hours | /api/v1/company_account_audits/recents |\n| recents/?last_update | Returns the objects evaluated from the given date (included) (format: `%d/%m/%Y`) | /api/v1/payment_checks/recents?last_update='01/01/2021' |\n| state | Filters by global state (in `pending`, `favorable`, `unfavorable`, `anomaly` or `unevaluated`) | api/v1/company_account_checks/?state=unfavorable |\n\n# HTTP Codes\n\nTrustpair uses conventional HTTP response codes to indicate the success or failure of an API request.\n\n| Code | Description |\n| ------------- |:-------------: |\n| 200 - OK | Everything worked as expected |\n| 202 - Accepted | The request has been accepted and processing has not been completed yet |\n| 401 - Unauthorized | No valid token was provided |\n| 403 - Forbidden | The token doesn't have permissions for the request |\n| 404 - Not found | The requested resource doesn't exist |\n| 422 - Unprocessable Entity | The request format was invalid |\n| 429 - Too many requests | The requests limit is exceeded |\n\n# Webhooks\n\nThe webhook events documentation can be found by selecting `Webhooks - V1` in the [definitions](#definitions) select.\n\n" }, "servers": [ { "url": "https://app-sandbox.trustpair.com/" } ], "paths": { "/api/v1/company_account_checks": { "get": { "summary": "Retrieve all company account checks", "tags": [ "Company account checks" ], "description": "Retrieves a list of company account checks associated with the authenticated customer.\n\nThis endpoint allows you to:\n- Filter company account checks by state, IDs, and last update date\n- Paginate results using cursor-based pagination\n\n**Required permissions:**\n- `company_account_checks_read`\n", "security": [ { "bearer": [] } ], "parameters": [ { "name": "Accept-Language", "in": "header", "schema": { "type": "string", "enum": [ "en", "fr" ] }, "required": false, "description": "Specifies the preferred language for the response. Supported languages:\n* `en` - English\n* `fr` - French\n\nIf not provided, the default language will be used.\n", "example": "en" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "required": false, "description": "Maximum number of company account checks to return in the response.\n\n**Constraints:**\n* Minimum: 1\n* Maximum: 100\n\nIf not specified, the default pagination limit will be applied.\n", "example": 10 }, { "name": "starting_after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "required": false, "description": "**Pagination cursor** - returns company account checks created *after* the company account check\nwith this ID.\n\n* Results are ordered by creation date\n* Cannot be used together with `ending_before`\n* Must be a valid UUID\n", "example": "123e4567-e89b-12d3-a456-426614174000" }, { "name": "ending_before", "in": "query", "schema": { "type": "string", "format": "uuid" }, "required": false, "description": "**Pagination cursor** - returns company account checks created *before* the company account check\nwith this ID.\n\n* Results are ordered by creation date\n* Cannot be used together with `starting_after`\n* Must be a valid UUID\n", "example": "123e4567-e89b-12d3-a456-426614174000" }, { "name": "last_update", "in": "query", "schema": { "type": "string", "format": "date" }, "required": false, "description": "Filters company account checks to include only those updated on or after the specified date.\n* Format: `YYYY-MM-DD`\n* Time component is set to the start of the day (00:00:00)\n", "example": "2023-10-15" }, { "name": "ids", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Comma-separated list of company account check IDs to filter the results.\n* Each ID must be a valid UUID\n", "example": "123e4567-e89b-12d3-a456-426614174000,987e6543-e21b-12d3-a456-426614174999" }, { "name": "state", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Comma-separated list of states to filter the company account checks.\n* Valid states: pending favorable unfavorable anomaly unevaluated\n", "example": "123e4567-e89b-12d3-a456-426614174000,987e6543-e21b-12d3-a456-426614174999" }, { "name": "tags", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Comma-separated list of tags to filter company account checks.\n* Only company account checks with at least one of the specified tags will be returned\n* Invalid or non-existent tags are silently ignored\n", "example": "vip,french-supplier" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/company_account_check" } }, "links": { "$ref": "#/components/schemas/links" }, "meta": { "$ref": "#/components/schemas/meta" } } } } } }, "401": { "description": "Unauthorized response code", "content": { "application/json": { "examples": { "With invalid token": { "value": { "message": "Bearer token invalid or missing" } } } } } }, "403": { "description": "Forbidden response code", "content": { "application/json": { "examples": { "Without required permissions": { "value": { "message": "Access requires any permission: 'company_account_checks_read', 'company_account_checks_write'" } } } } } }, "422": { "description": "Unprocessable Content response code", "content": { "application/json": { "examples": { "With valid & invalid tags filter": { "value": { "message": "Tags is not included in the list", "errors": [ { "code": "inclusion", "title": "is not included in the list", "detail": "Tags is not included in the list", "source": { "parameter": "tags" } } ] } }, "With invalid tags filter": { "value": { "message": "Tags is not included in the list", "errors": [ { "code": "inclusion", "title": "is not included in the list", "detail": "Tags is not included in the list", "source": { "parameter": "tags" } } ] } } } } } } } } } }, "tags": [ { "name": "Company account checks", "description": "Check company account data in real time.\n You can submit and retrieve a company account check object to get the Trustpair\n evaluation of a given company or natural person and bank account." } ], "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer" } }, "schemas": { "address": { "type": "object", "properties": { "street": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "country_code": { "type": "string", "nullable": true }, "zip_code": { "type": "string", "nullable": true } }, "nullable": true }, "meta": { "type": "object", "properties": { "count": { "type": "integer", "example": 10 }, "total": { "type": "integer", "example": 122 } } }, "links": { "type": "object", "properties": { "self": { "type": "string", "example": "https://trustpair.com/api/v1/resources?starting_after=4b9a21a1-c3e7-4635-8df2-5775a1603152" }, "first": { "type": "string", "example": "https://trustpair.com/api/v1/resources" }, "next": { "type": "string", "nullable": true, "example": "https://trustpair.com/api/v1/resources?starting_after=4b9a21a1-c3e7-4635-8df2-5775a1603152" }, "prev": { "type": "string", "nullable": true, "example": "https://trustpair.com/api/v1/resources?ending_before=4b9a21a1-c3e7-4635-8df2-5775a1603152" } } }, "company_account_check": { "type": "object", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "814a56f9-64d7-43e6-916a-b0bafe568a2b" }, "type": { "type": "string", "enum": [ "company_account_check" ] }, "attributes": { "type": "object", "properties": { "custom_id": { "type": "string", "nullable": true, "example": "something_meaningful_123" }, "company_name": { "type": "string", "nullable": true, "example": "Company name" }, "company_country_code": { "type": "string", "nullable": true, "example": "FR" }, "company_country_code_iso3": { "type": "string", "nullable": true, "example": "FRA" }, "company_registration": { "type": "string", "nullable": true, "example": "B859102711" }, "tax_number": { "type": "string", "nullable": true }, "duns": { "type": "string", "nullable": true }, "company_raw_address": { "type": "string", "nullable": true }, "company_details": { "type": "object", "nullable": true, "additionalProperties": false, "properties": { "name": { "type": "string", "nullable": true }, "commercial_name": { "type": "string", "nullable": true }, "address": { "$ref": "#/components/schemas/address" }, "employees": { "type": "string", "nullable": true }, "legal_form": { "type": "string", "nullable": true }, "opening_date": { "type": "integer", "description": "Unix timestamp (seconds)", "nullable": true }, "dissolution_date": { "type": "integer", "description": "Unix timestamp (seconds)", "nullable": true }, "activity": { "type": "object", "nullable": true, "additionalProperties": false, "properties": { "code": { "type": "string", "nullable": true }, "label": { "type": "string", "nullable": true }, "type": { "type": "string", "nullable": true } } }, "insolvencies": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "date": { "type": "string", "description": "Published at - YYYY-MM-DD", "nullable": false }, "url": { "type": "string", "nullable": false } } } }, "enriched_by": { "type": "string", "description": "How the supplier was enriched", "nullable": true, "enum": [ "company_registration", "company_name_address" ] } } }, "iban": { "type": "string", "nullable": true }, "bank_account_country_code": { "type": "string", "nullable": true }, "bank_account_country_code_iso3": { "type": "string", "nullable": true }, "bank_account_number": { "type": "string", "nullable": true }, "bank_account_bic": { "type": "string", "nullable": true }, "routing_number": { "type": "string", "nullable": true }, "control_key": { "type": "string", "nullable": true }, "bank_details": { "type": "object", "nullable": true, "additionalProperties": false, "properties": { "account_blacklisted": { "type": "boolean", "nullable": true }, "factor": { "type": "boolean", "nullable": true }, "name": { "type": "string", "nullable": true }, "address": { "$ref": "#/components/schemas/address" } } }, "state": { "type": "string", "enum": [ "anomaly", "favorable", "pending", "unfavorable", "unevaluated" ] }, "state_reasons": { "type": "object", "additionalProperties": false, "properties": { "company": { "$ref": "#/components/schemas/entity_state_reasons" }, "bank_account": { "$ref": "#/components/schemas/entity_state_reasons" }, "correlation": { "$ref": "#/components/schemas/entity_state_reasons" }, "supplier_sanctions_screening": { "$ref": "#/components/schemas/entity_state_reasons" }, "bank_sanctions_screening": { "$ref": "#/components/schemas/entity_state_reasons" } } }, "requested_at": { "type": "integer", "description": "Unix timestamp (seconds)" }, "requested_via_api": { "type": "boolean" }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "middle_name": { "type": "string", "nullable": true }, "other_name": { "type": "string", "nullable": true }, "archived_at": { "type": "string", "format": "date-time", "nullable": true }, "archived_by_full_name": { "type": "string", "nullable": true }, "birthdate": { "type": "string", "description": "DD-MM-YYYY", "nullable": true }, "natural_person_country_code": { "type": "string", "nullable": true }, "natural_person_country_code_iso3": { "type": "string", "nullable": true }, "natural_person_tax_number": { "type": "string", "nullable": true }, "override_initial_status": { "type": "string", "nullable": true }, "override_request_date": { "type": "string", "nullable": true }, "override_request_initiator": { "type": "string", "nullable": true }, "override_review_date": { "type": "string", "nullable": true }, "override_request_reviewer": { "type": "string", "nullable": true }, "contact_email": { "type": "string", "nullable": true }, "contact_first_name": { "type": "string", "nullable": true }, "contact_last_name": { "type": "string", "nullable": true }, "contact_department": { "type": "string", "nullable": true, "enum": [ "accounting", "financial", "other", "procurement", "treasury" ] }, "tax_id_match": { "$ref": "#/components/schemas/tax_id_match" }, "tags": { "type": "array", "description": "Array of strings, each item is a separated tag", "items": { "type": "string", "description": "A single tag value", "example": "tag1" } } } }, "links": { "type": "object", "required": [ "details_in_app" ], "properties": { "details_in_app": { "type": "string", "format": "uri" } } } } }, "entity_state_reasons": { "oneOf": [ { "type": "object", "nullable": true, "additionalProperties": false, "maxProperties": 0, "description": "May be an empty object" }, { "type": "object", "nullable": true, "additionalProperties": false, "required": [ "raw", "state", "state_reasons" ], "properties": { "raw": { "type": "array", "items": { "type": "string" } }, "state": { "type": "string", "nullable": true, "description": "State for this sub-entity" }, "state_reasons": { "type": "array", "items": { "type": "string" } } } } ] }, "tax_id_match": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "pending", "favorable", "unfavorable", "anomaly", "bypassed" ] }, "state_reason": { "type": "string", "description": "A human-readable label for the TIN match result" } } } } } } ```