> ## Documentation Index > Fetch the complete documentation index at: https://v2.docs.conduit.financial/llms.txt > Use this file to discover all available pages before exploring further. # List customers > Returns a paginated list of customers belonging to the authenticated organization. Customers are created after a successful onboarding application. Each customer has a type (business or individual) with the corresponding profile populated. Supports cursor-based pagination and filtering by type. ## OpenAPI ````yaml https://api.sandbox.conduit.financial/v2/api-docs/openapi.json get /customers openapi: 3.0.0 info: title: Conduit Sandbox API description: >- **Sandbox API** — clients integrate against this surface to exercise happy and unhappy paths without consuming real KYC/PSP credits or moving real money. Customer KYC, banking partners, and crypto custody are stubbed; org-level KYB runs against real providers. Simulation endpoints under `/v2/sandbox/*` drive specific scenarios. Internal and portal endpoints are excluded from this spec. version: '2.0' contact: {} servers: - url: https://api.sandbox.conduit.financial/v2 description: Sandbox - url: https://api.conduit.financial/v2 description: Production security: - api-key: [] tags: - name: Customers - name: Registered Addresses - name: Wallets - name: Wallet Signers - name: Signing Quorum - name: Virtual Accounts - name: Applications - name: Documents - name: Verifications - name: Signing Requests - name: Transactions - name: Payouts - name: Whitelist Recipients - name: Orders - name: RFIs - name: Webhook Endpoints - name: Webhook Deliveries - name: Webhook Event Types - name: Features - name: Customer Onboarding - name: Sandbox paths: /customers: get: tags: - Customers summary: List customers description: >- Returns a paginated list of customers belonging to the authenticated organization. Customers are created after a successful onboarding application. Each customer has a type (business or individual) with the corresponding profile populated. Supports cursor-based pagination and filtering by type. operationId: CustomersController_findAll_v2 parameters: - name: cursor required: false in: query description: Opaque cursor from a previous response to fetch the next page schema: type: string - name: limit required: false in: query description: Maximum number of results to return (1-100) schema: minimum: 1 maximum: 100 default: 20 type: number - name: direction required: false in: query description: Pagination direction relative to the cursor schema: enum: - forward - backward type: string - name: clientReferenceId required: false in: query description: >- Filter to the customer with this client reference ID. 1-255 characters from A-Za-z, 0-9, underscore, hyphen, colon, and period — no spaces. schema: type: string - name: type required: false in: query description: Filter by one or more customer types. schema: type: array items: type: string - name: sortBy required: false in: query schema: enum: - createdAt - updatedAt - type type: string - name: sortOrder required: false in: query schema: enum: - asc - desc type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/CustomerPaginatedResponseDto' '400': description: >- **INVALID_OID_FORMAT**: A path or query parameter expected a valid object identifier but received a value that does not match the expected format. **INVALID_CURSOR**: The pagination cursor provided in the request is malformed or has expired. content: application/json: schema: $ref: '#/components/schemas/ValidationErrorDto' example: type: INVALID_OID_FORMAT title: Invalid Object ID Format status: 400 detail: >- A path or query parameter expected a valid object identifier but received a value that does not match the expected format. resolution: >- Verify that all IDs in the request URL and query parameters are correctly formatted. IDs are typically prefixed strings like 'cus_...', 'app_...', or 'doc_...'. docs: https://conduit-v2.mintlify.app/errors#invalid-oid-format instance: /v2/... correlationId: req_a1b2c3d4 timestamp: '2026-01-15T09:30:00.000Z' '401': description: >- **API_KEY_MISSING**: The request did not include an API key. All API requests must be authenticated. **API_KEY_INVALID**: The provided API key is not recognized or has been revoked. content: application/json: schema: $ref: '#/components/schemas/ProblemDetailDto' example: type: API_KEY_MISSING title: API Key Missing status: 401 detail: >- The request did not include an API key. All API requests must be authenticated. resolution: >- Include your API key in the 'x-api-key' header with every request. docs: https://conduit-v2.mintlify.app/errors#api-key-missing instance: /v2/... correlationId: req_a1b2c3d4 timestamp: '2026-01-15T09:30:00.000Z' '429': description: >- **RATE_LIMITED**: Too many requests. This error is returned by three independent checks: the per-organization bucket applied to every authenticated API request; the per-IP bucket applied to unauthenticated traffic before an API key is validated; and the per-IP bucket applied when repeated invalid API keys are submitted from the same address. Honor the Retry-After header (also exposed as retryAfterSeconds in the body) before retrying. Current limits and remaining budget are visible in X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset on rate-limited route responses. content: application/json: schema: $ref: '#/components/schemas/RateLimitedErrorDto' example: type: RATE_LIMITED title: Rate Limited status: 429 detail: >- Too many requests. This error is returned by three independent checks: the per-organization bucket applied to every authenticated API request; the per-IP bucket applied to unauthenticated traffic before an API key is validated; and the per-IP bucket applied when repeated invalid API keys are submitted from the same address. Honor the Retry-After header (also exposed as retryAfterSeconds in the body) before retrying. Current limits and remaining budget are visible in X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset on rate-limited route responses. resolution: >- Sleep until Retry-After seconds have elapsed, then retry. For sustained workloads exceeding the per-organization defaults, request a rate-limit increase through your support contact. docs: https://conduit-v2.mintlify.app/errors#rate-limited instance: /v2/... correlationId: req_a1b2c3d4 timestamp: '2026-01-15T09:30:00.000Z' retryAfterSeconds: 3 '500': description: >- **INTERNAL_ERROR**: An unexpected error occurred while processing your request. content: application/json: schema: $ref: '#/components/schemas/ProblemDetailDto' example: type: INTERNAL_ERROR title: Internal Error status: 500 detail: An unexpected error occurred while processing your request. resolution: >- Retry the request after a brief delay. If the error persists, contact support and include the correlationId from the error response for investigation. docs: https://conduit-v2.mintlify.app/errors#internal-error instance: /v2/... correlationId: req_a1b2c3d4 timestamp: '2026-01-15T09:30:00.000Z' components: schemas: CustomerPaginatedResponseDto: type: object properties: data: type: array items: oneOf: - type: object properties: id: type: string pattern: ^cus_[0-9A-Za-z]{22}$ description: Unique customer identifier clientReferenceId: description: >- Client-provided external identifier for cross-referencing. 1-255 characters from A-Za-z, 0-9, underscore, hyphen, colon, and period — no spaces. example: client-cus-001 type: string pattern: ^[A-Za-z0-9_\-:.]{1,255}$ applicationId: type: string pattern: ^app_[0-9A-Za-z]{22}$ description: >- ID of the onboarding application that created this customer. createdAt: type: string format: date-time description: Timestamp when the customer was created example: '2026-01-15T09:30:00.000Z' updatedAt: type: string format: date-time description: Timestamp when the customer was last modified example: '2026-01-15T09:30:00.000Z' features: type: array items: type: object properties: feature: description: Feature identifier type: string enum: - virtual_account - crypto_wallet isActive: type: boolean description: >- Whether this feature is currently active for the customer example: true required: - feature - isActive description: List of features enabled for this customer isHouseAccount: type: boolean description: >- Whether this customer is the organization's own house account rather than an external customer. Read-only. example: false type: type: string enum: - business legalName: type: string description: Registered legal name of the business example: Acme Payments Inc. tradeName: description: Doing-business-as name. Omitted if same as legal name. example: Acme Pay type: string registrationNumber: description: Business registration or incorporation number example: '12345678' type: string taxId: type: string description: >- Government-issued tax identifier (e.g. EIN for US businesses). example: 12-3456789 registeredAddress: type: object properties: addressLine1: type: string description: Primary street address example: 100 Market St addressLine2: description: Secondary address line (suite, floor, etc.) example: Suite 400 type: string city: type: string description: City example: San Francisco state: description: State or province example: CA type: string postalCode: description: Postal code example: '94105' type: string country: type: string enum: - AF - AL - DZ - AS - AD - AO - AI - AQ - AG - AR - AM - AW - AU - AT - AZ - BS - BH - BD - BB - BY - BE - BZ - BJ - BM - BT - BO - BQ - BA - BW - BV - BR - IO - BN - BG - BF - BI - CV - KH - CM - CA - KY - CF - TD - CL - CN - CX - CC - CO - KM - CG - CD - CK - CR - CI - HR - CU - CW - CY - CZ - DK - DJ - DM - DO - EC - EG - SV - GQ - ER - EE - SZ - ET - FK - FO - FJ - FI - FR - GF - PF - TF - GA - GM - GE - DE - GH - GI - GR - GL - GD - GP - GU - GT - GG - GN - GW - GY - HT - HM - VA - HN - HK - HU - IS - IN - ID - IR - IQ - IE - IM - IL - IT - JM - JP - JE - JO - KZ - KE - KI - KP - KR - KW - KG - LA - LV - LB - LS - LR - LY - LI - LT - LU - MO - MG - MW - MY - MV - ML - MT - MH - MQ - MR - MU - YT - MX - FM - MD - MC - MN - ME - MS - MA - MZ - MM - NA - NR - NP - NL - NC - NZ - NI - NE - NG - NU - NF - MK - MP - 'NO' - OM - PK - PW - PS - PA - PG - PY - PE - PH - PN - PL - PT - PR - QA - RE - RO - RU - RW - BL - SH - KN - LC - MF - PM - VC - WS - SM - ST - SA - SN - RS - SC - SL - SG - SX - SK - SI - SB - SO - ZA - GS - SS - ES - LK - SD - SR - SJ - SE - CH - SY - TW - TJ - TZ - TH - TL - TG - TK - TO - TT - TN - TR - TM - TC - TV - UG - UA - AE - GB - US - UM - UY - UZ - VU - VE - VN - VG - VI - WF - EH - YE - ZM - ZW description: Country (ISO 3166-1 alpha-2) example: US required: - addressLine1 - city - country description: >- Registered office address. Same nested shape the onboarding request submits, so it round-trips field-for-field. dateOfIncorporation: type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ description: Date the business was incorporated (YYYY-MM-DD) example: '2020-03-15' website: description: Business website URL example: https://acmepay.com type: string legalStructure: type: string description: >- Legal structure of the business — the local jurisdiction name the customer declared at onboarding (e.g. 'Sociedade Limitada', 'GmbH', 'C-Corporation'). Free-form string; the available options are jurisdiction-specific and surfaced by the requirements discovery endpoint. example: Sociedade Limitada coreIndustry: description: Primary industry classification of the business example: Financial Technology type: string enum: - Agriculture - Mining - Manufacturing - Retail/Wholesale - Healthcare - Real Estate - Transport/Logistics - Energy - Education - Financial Technology - Professional Services - Hospitality - Construction - Telecommunications - Other contactEmail: type: string description: Primary business contact email example: compliance@acmepay.com contactPhone: description: Primary business contact phone number example: '+14155551234' type: string required: - id - applicationId - createdAt - updatedAt - features - isHouseAccount - type - legalName - taxId - registeredAddress - dateOfIncorporation - legalStructure - contactEmail - type: object properties: id: type: string pattern: ^cus_[0-9A-Za-z]{22}$ description: Unique customer identifier clientReferenceId: description: >- Client-provided external identifier for cross-referencing. 1-255 characters from A-Za-z, 0-9, underscore, hyphen, colon, and period — no spaces. example: client-cus-001 type: string pattern: ^[A-Za-z0-9_\-:.]{1,255}$ applicationId: type: string pattern: ^app_[0-9A-Za-z]{22}$ description: >- ID of the onboarding application that created this customer. createdAt: type: string format: date-time description: Timestamp when the customer was created example: '2026-01-15T09:30:00.000Z' updatedAt: type: string format: date-time description: Timestamp when the customer was last modified example: '2026-01-15T09:30:00.000Z' features: type: array items: type: object properties: feature: description: Feature identifier type: string enum: - virtual_account - crypto_wallet isActive: type: boolean description: >- Whether this feature is currently active for the customer example: true required: - feature - isActive description: List of features enabled for this customer isHouseAccount: type: boolean description: >- Whether this customer is the organization's own house account rather than an external customer. Read-only. example: false type: type: string enum: - individual firstName: type: string description: Individual's first name example: Jane lastName: type: string description: Individual's last name example: Doe middleName: description: Individual's middle name. Omitted if not provided. example: Marie type: string email: type: string description: Individual's email address example: jane.doe@example.com phone: description: Individual's phone number in E.164 format example: '+14155559876' type: string birthDate: type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ description: Date of birth (YYYY-MM-DD) example: '1990-05-20' nationality: type: string enum: - AF - AL - DZ - AS - AD - AO - AI - AQ - AG - AR - AM - AW - AU - AT - AZ - BS - BH - BD - BB - BY - BE - BZ - BJ - BM - BT - BO - BQ - BA - BW - BV - BR - IO - BN - BG - BF - BI - CV - KH - CM - CA - KY - CF - TD - CL - CN - CX - CC - CO - KM - CG - CD - CK - CR - CI - HR - CU - CW - CY - CZ - DK - DJ - DM - DO - EC - EG - SV - GQ - ER - EE - SZ - ET - FK - FO - FJ - FI - FR - GF - PF - TF - GA - GM - GE - DE - GH - GI - GR - GL - GD - GP - GU - GT - GG - GN - GW - GY - HT - HM - VA - HN - HK - HU - IS - IN - ID - IR - IQ - IE - IM - IL - IT - JM - JP - JE - JO - KZ - KE - KI - KP - KR - KW - KG - LA - LV - LB - LS - LR - LY - LI - LT - LU - MO - MG - MW - MY - MV - ML - MT - MH - MQ - MR - MU - YT - MX - FM - MD - MC - MN - ME - MS - MA - MZ - MM - NA - NR - NP - NL - NC - NZ - NI - NE - NG - NU - NF - MK - MP - 'NO' - OM - PK - PW - PS - PA - PG - PY - PE - PH - PN - PL - PT - PR - QA - RE - RO - RU - RW - BL - SH - KN - LC - MF - PM - VC - WS - SM - ST - SA - SN - RS - SC - SL - SG - SX - SK - SI - SB - SO - ZA - GS - SS - ES - LK - SD - SR - SJ - SE - CH - SY - TW - TJ - TZ - TH - TL - TG - TK - TO - TT - TN - TR - TM - TC - TV - UG - UA - AE - GB - US - UM - UY - UZ - VU - VE - VN - VG - VI - WF - EH - YE - ZM - ZW description: Country of nationality (ISO 3166-1 alpha-2) example: US taxIdType: description: >- The person's tax identification type (SSN for US persons, national tax ID otherwise). Omitted for non-US persons who owe no tax ID. example: SSN type: string enum: - PASSPORT - NATIONAL_ID - DRIVER_LICENSE - RESIDENT_CARD - SSN taxIdCountry: description: >- Country whose tax authority issued the tax ID (ISO 3166-1 alpha-2). Omitted for non-US persons who owe no tax ID. example: US type: string enum: - AF - AL - DZ - AS - AD - AO - AI - AQ - AG - AR - AM - AW - AU - AT - AZ - BS - BH - BD - BB - BY - BE - BZ - BJ - BM - BT - BO - BQ - BA - BW - BV - BR - IO - BN - BG - BF - BI - CV - KH - CM - CA - KY - CF - TD - CL - CN - CX - CC - CO - KM - CG - CD - CK - CR - CI - HR - CU - CW - CY - CZ - DK - DJ - DM - DO - EC - EG - SV - GQ - ER - EE - SZ - ET - FK - FO - FJ - FI - FR - GF - PF - TF - GA - GM - GE - DE - GH - GI - GR - GL - GD - GP - GU - GT - GG - GN - GW - GY - HT - HM - VA - HN - HK - HU - IS - IN - ID - IR - IQ - IE - IM - IL - IT - JM - JP - JE - JO - KZ - KE - KI - KP - KR - KW - KG - LA - LV - LB - LS - LR - LY - LI - LT - LU - MO - MG - MW - MY - MV - ML - MT - MH - MQ - MR - MU - YT - MX - FM - MD - MC - MN - ME - MS - MA - MZ - MM - NA - NR - NP - NL - NC - NZ - NI - NE - NG - NU - NF - MK - MP - 'NO' - OM - PK - PW - PS - PA - PG - PY - PE - PH - PN - PL - PT - PR - QA - RE - RO - RU - RW - BL - SH - KN - LC - MF - PM - VC - WS - SM - ST - SA - SN - RS - SC - SL - SG - SX - SK - SI - SB - SO - ZA - GS - SS - ES - LK - SD - SR - SJ - SE - CH - SY - TW - TJ - TZ - TH - TL - TG - TK - TO - TT - TN - TR - TM - TC - TV - UG - UA - AE - GB - US - UM - UY - UZ - VU - VE - VN - VG - VI - WF - EH - YE - ZM - ZW taxResidencyCountry: description: >- Country of tax residency (ISO 3166-1 alpha-2). Omitted if not provided. example: US type: string enum: - AF - AL - DZ - AS - AD - AO - AI - AQ - AG - AR - AM - AW - AU - AT - AZ - BS - BH - BD - BB - BY - BE - BZ - BJ - BM - BT - BO - BQ - BA - BW - BV - BR - IO - BN - BG - BF - BI - CV - KH - CM - CA - KY - CF - TD - CL - CN - CX - CC - CO - KM - CG - CD - CK - CR - CI - HR - CU - CW - CY - CZ - DK - DJ - DM - DO - EC - EG - SV - GQ - ER - EE - SZ - ET - FK - FO - FJ - FI - FR - GF - PF - TF - GA - GM - GE - DE - GH - GI - GR - GL - GD - GP - GU - GT - GG - GN - GW - GY - HT - HM - VA - HN - HK - HU - IS - IN - ID - IR - IQ - IE - IM - IL - IT - JM - JP - JE - JO - KZ - KE - KI - KP - KR - KW - KG - LA - LV - LB - LS - LR - LY - LI - LT - LU - MO - MG - MW - MY - MV - ML - MT - MH - MQ - MR - MU - YT - MX - FM - MD - MC - MN - ME - MS - MA - MZ - MM - NA - NR - NP - NL - NC - NZ - NI - NE - NG - NU - NF - MK - MP - 'NO' - OM - PK - PW - PS - PA - PG - PY - PE - PH - PN - PL - PT - PR - QA - RE - RO - RU - RW - BL - SH - KN - LC - MF - PM - VC - WS - SM - ST - SA - SN - RS - SC - SL - SG - SX - SK - SI - SB - SO - ZA - GS - SS - ES - LK - SD - SR - SJ - SE - CH - SY - TW - TJ - TZ - TH - TL - TG - TK - TO - TT - TN - TR - TM - TC - TV - UG - UA - AE - GB - US - UM - UY - UZ - VU - VE - VN - VG - VI - WF - EH - YE - ZM - ZW required: - id - applicationId - createdAt - updatedAt - features - isHouseAccount - type - firstName - lastName - email - birthDate - nationality meta: type: object properties: mode: type: string description: Pagination mode example: cursor enum: - cursor nextCursor: type: string description: Cursor for the next page, null if no more results example: eyJpZCI6ImN1c18yeFBxTjhSIn0 nullable: true previousCursor: type: string description: Cursor for the previous page, null if at the start example: null nullable: true total: type: number description: Total number of records matching the query example: 42 required: - mode - nextCursor - previousCursor - total required: - data - meta ValidationErrorDto: type: object properties: type: type: string description: Machine-readable error code example: CUSTOMER_NOT_FOUND title: type: string description: Human-readable error type label example: Customer Not Found status: type: number description: HTTP status code example: 404 detail: type: string description: Human-readable explanation of this occurrence example: Customer with id cus_abc123 not found resolution: type: string description: What the developer should do to resolve this error example: >- Verify the customer ID. Check you are using the correct API key for this organization. docs: type: string description: URL to error documentation example: https://conduit-v2.mintlify.app/errors#customer-not-found instance: type: string description: Request path that produced the error example: /v2/customers/cus_abc123 correlationId: description: Request correlation ID example: req_a1b2c3d4 type: string timestamp: type: string description: ISO 8601 UTC timestamp example: '2026-04-27T20:00:00.000Z' details: description: >- Additional structured data for domain-specific errors (e.g. missing field lists, pair info) errors: type: array items: type: object properties: pointer: type: string description: JSON pointer to the invalid field example: /email detail: type: string description: What is wrong with this field example: Invalid email format allowedValues: description: The values this field accepts, when it is a closed set example: - ach - fedwire - rtp type: array items: type: string category: description: >- Class of blocker (requirements-validator output only). 'field' = form-field gap, 'document' = missing or insufficient document (including per-UBO document slots), 'individual' = required person missing. example: field type: string enum: - field - document - individual required: - pointer - detail required: - type - title - status - detail - resolution - docs - instance - timestamp ProblemDetailDto: type: object properties: type: type: string description: Machine-readable error code example: CUSTOMER_NOT_FOUND title: type: string description: Human-readable error type label example: Customer Not Found status: type: number description: HTTP status code example: 404 detail: type: string description: Human-readable explanation of this occurrence example: Customer with id cus_abc123 not found resolution: type: string description: What the developer should do to resolve this error example: >- Verify the customer ID. Check you are using the correct API key for this organization. docs: type: string description: URL to error documentation example: https://conduit-v2.mintlify.app/errors#customer-not-found instance: type: string description: Request path that produced the error example: /v2/customers/cus_abc123 correlationId: description: Request correlation ID example: req_a1b2c3d4 type: string timestamp: type: string description: ISO 8601 UTC timestamp example: '2026-04-27T20:00:00.000Z' details: description: >- Additional structured data for domain-specific errors (e.g. missing field lists, pair info) required: - type - title - status - detail - resolution - docs - instance - timestamp RateLimitedErrorDto: type: object properties: type: type: string description: Machine-readable error code example: CUSTOMER_NOT_FOUND title: type: string description: Human-readable error type label example: Customer Not Found status: type: number description: HTTP status code example: 404 detail: type: string description: Human-readable explanation of this occurrence example: Customer with id cus_abc123 not found resolution: type: string description: What the developer should do to resolve this error example: >- Verify the customer ID. Check you are using the correct API key for this organization. docs: type: string description: URL to error documentation example: https://conduit-v2.mintlify.app/errors#customer-not-found instance: type: string description: Request path that produced the error example: /v2/customers/cus_abc123 correlationId: description: Request correlation ID example: req_a1b2c3d4 type: string timestamp: type: string description: ISO 8601 UTC timestamp example: '2026-04-27T20:00:00.000Z' details: description: >- Additional structured data for domain-specific errors (e.g. missing field lists, pair info) retryAfterSeconds: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 description: Seconds to wait before retrying example: 3 required: - type - title - status - detail - resolution - docs - instance - timestamp - retryAfterSeconds securitySchemes: api-key: type: apiKey in: header name: x-api-key ````