> ## Documentation Index > Fetch the complete documentation index at: https://hevninc.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > HEVN has two products and they authorize money differently. Self-serve (the General tab): the person who owns the email holds the only key and signs for themselves. Whitelabel (the Whitelabel and REST API tabs): the integrator's backend holds a developer key, signs on behalf of client accounts it created, and HEVN co-signs. Never mix the two models in an answer. > Use HEVN's terms exactly. A rail is a bank route a client can request. A virtual account (bnk_) is an opened rail. Account details are what a payer needs in order to wire money, and arrive in a field named requisites. A client is an account the integrator created; the business behind it is the integrator's customer. A contact is a saved destination; a beneficiary is the party at the far end of a fiat payout. Every departure of money is a payout, to a bank account or to a wallet alike. > Never name a banking partner. Say 'a licensed banking partner'. > There are no published fee rates, spreads or minimums. Prices come from a quote on a specific payment; direct pricing questions to HEVN rather than inventing numbers. > The whitelabel API is at /dapi/v1 and takes a developer-key session plus an X-Hevn-Account header. The CLI uses an app API key in X-Api-Key. They are different credentials and neither works on the other surface. # List saved contacts > List saved contacts using opaque cursor pagination. ## OpenAPI ````yaml /openapi.json get /contacts openapi: 3.1.0 info: title: HEVN Platform API description: >- HEVN's account, verification and money-movement API. Verification follows a submission workflow: save applicant info and documents, inspect outstanding requirements, then explicitly complete the submission to send an immutable snapshot for review. Completing a submission is separate from editing it. version: 1.0.0 servers: [] security: [] tags: - name: auth description: Authenticate an integration and issue short-lived account sessions. - name: accounts description: Create and manage business or individual customer accounts. - name: verification description: >- Collect business-applicant and related-individual information, inspect requirements, and complete a verification submission for review. - name: documents description: Upload verification and payment evidence for later reference by id. - name: virtual accounts description: Discover payment methods and create persistent receiving account details. - name: transfers description: Quote, create, authorize and track incoming or outgoing transfers. - name: contacts description: Create saved contacts and inspect their available payment channels. - name: transactions description: Read and export the account ledger. - name: escrow description: Create, authorize and reconcile on-chain escrow agreements. - name: sandbox description: Emulate funding and lifecycle events in the sandbox environment. paths: /contacts: get: tags: - contacts summary: List saved contacts description: List saved contacts using opaque cursor pagination. operationId: list_contacts_contacts_get parameters: - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 default: 50 title: Limit - name: cursor in: query required: false schema: anyOf: - type: string maxLength: 512 - type: 'null' title: Cursor - name: X-Hevn-Account in: header required: false schema: anyOf: - type: string - type: 'null' description: >- The client account to act for, as a `cl_…` id. Omit it to act as yourself. examples: - cl_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41 title: X-Hevn-Account description: >- The client account to act for, as a `cl_…` id. Omit it to act as yourself. - name: x-api-key in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Page_ContactResponse_' '422': description: Request validation failed content: application/json: schema: $ref: '#/components/schemas/PlatformErrorResponse' security: - HTTPBearer: [] components: schemas: Page_ContactResponse_: properties: items: items: $ref: '#/components/schemas/ContactResponse' type: array title: Items description: Resources in this page, in stable server-defined order. nextCursor: anyOf: - type: string - type: 'null' title: Nextcursor description: Opaque cursor for the next page; absent when this is the final page. type: object required: - items title: Page[ContactResponse] PlatformErrorResponse: properties: error: $ref: '#/components/schemas/PlatformErrorBody' description: Public error body. type: object required: - error title: PlatformErrorResponse ContactResponse: properties: id: type: string pattern: ^(?:ct_)?[A-Za-z0-9._:\-]{1,216}$ title: Id description: Stable public identifier for this contact. examples: - ct_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41 name: type: string title: Name description: Human-readable contact name. isExternal: type: boolean title: Isexternal description: Whether the contact is outside the selected account. createdAt: type: string format: date-time title: Createdat description: UTC timestamp when the contact was created. email: anyOf: - type: string - type: 'null' title: Email description: Email associated with an existing HEVN contact. address: anyOf: - $ref: '#/components/schemas/UserAddress' - type: 'null' description: Postal address of the contact or account holder. bank: anyOf: - $ref: '#/components/schemas/ContactPaymentAccountView' - type: 'null' description: Payment-account destination details. crypto: anyOf: - $ref: '#/components/schemas/ContactCryptoView' - type: 'null' description: On-chain destination details. userId: anyOf: - type: string format: uuid - type: 'null' title: Userid description: Account behind an existing HEVN contact. user: anyOf: - $ref: '#/components/schemas/ContactLinkedUserView' - type: 'null' description: Profile of the linked HEVN account. type: object required: - id - name - isExternal - createdAt title: ContactResponse PlatformErrorBody: properties: code: $ref: '#/components/schemas/PlatformErrorCode' description: Stable machine-readable error code. message: type: string title: Message description: Human-readable explanation safe to show to an end user. details: anyOf: - additionalProperties: true type: object - type: 'null' title: Details description: Structured context for this error, when available. type: object required: - code - message title: PlatformErrorBody UserAddress: properties: streetAddress: anyOf: - type: string - type: 'null' title: Streetaddress description: Street name and building number. addressLine2: anyOf: - type: string - type: 'null' title: Addressline2 description: Optional apartment, suite or unit. city: anyOf: - type: string - type: 'null' title: City description: City or locality. state: anyOf: - type: string - type: 'null' title: State description: State, province or administrative area. country: anyOf: - $ref: '#/components/schemas/CountryCode' - type: 'null' description: ISO 3166-1 alpha-2 country code. zip: anyOf: - type: string - type: 'null' title: Zip description: Postal or ZIP code. type: object title: UserAddress description: Provider-neutral postal address used across domain and API schemas. ContactPaymentAccountView: properties: method: type: string title: Method description: Local payment method used to reach this contact. currency: type: string title: Currency description: ISO 4217 currency code accepted by the contact account. fields: $ref: '#/components/schemas/RequisiteFields' description: Structured destination account details. holder: $ref: '#/components/schemas/RequisiteHolder-Output' description: Identity and address of the destination account holder. bankName: anyOf: - type: string - type: 'null' title: Bankname description: Name of the destination financial institution. bankAddress: anyOf: - $ref: '#/components/schemas/BankAddress' - type: 'null' description: Postal address of the destination institution. intermediaryBank: anyOf: - $ref: '#/components/schemas/IntermediaryBank' - type: 'null' description: >- Optional intermediary institution used to route an international transfer. paymentReference: anyOf: - type: string - type: 'null' title: Paymentreference description: Reference or memo required by the contact. destinationAccount: anyOf: - $ref: '#/components/schemas/BalanceAccount' - type: 'null' description: Digital asset used to settle this method. state: $ref: '#/components/schemas/RequisiteState' description: Current usability state of the contact details. minimumDeposit: anyOf: - type: string example: '500.00' - type: 'null' title: Minimumdeposit description: Minimum amount accepted by this destination. type: object required: - method - currency - fields - holder - state title: ContactPaymentAccountView description: Public payment-account details with infrastructure identifiers removed. ContactCryptoView: properties: chain: anyOf: - type: string - type: 'null' title: Chain description: Blockchain network identifier. token: anyOf: - type: string - type: 'null' title: Token description: Digital asset accepted by this address. address: type: string title: Address description: On-chain destination address. type: object required: - address title: ContactCryptoView ContactLinkedUserView: properties: avatar: anyOf: - type: string - type: 'null' title: Avatar description: Avatar of the linked HEVN account. name: anyOf: - type: string - type: 'null' title: Name description: Display name of the linked HEVN account. type: object title: ContactLinkedUserView PlatformErrorCode: type: string enum: - invalid_request - validation_failed - invalid_cursor - invalid_id - idempotency_key_invalid - idempotency_key_reused - unauthenticated - token_expired - forbidden - not_found - method_not_allowed - conflict - gone - payload_too_large - rate_limited - provider_unavailable - database_unavailable - internal_error - invalid_credentials - request_expired - challenge_not_found - challenge_consumed - challenge_expired - signature_invalid - key_not_registered - signer_not_attached - wallet_not_linked - approval_consumed - approval_expired - approval_mismatch - signing_policy_refused - login_unavailable - login_mode_unavailable - developer_key_not_found - developer_key_already_exists - account_header_invalid - account_scope_conflict - account_not_found - account_forbidden - account_read_only - account_not_controlled - contact_not_found - quote_not_submitted - quote_not_fundable - funding_mode_unsupported - funding_token_unsupported - insufficient_funds - smart_wallet_not_deployed - wallet_owner_unverified - already_funded - payment_slot_consumed - funding_in_progress - funding_attempt_expired - contact_changed - user_operation_rejected - user_operation_unavailable - integrator_inactive - client_creation_not_enabled - email_in_use - name_in_use - client_request_conflict - client_not_found - profile_locked - contact_not_payable - contact_chain_unsupported - contact_token_unsupported - contact_payment_details_invalid - amount_below_minimum - amount_above_maximum - amount_precision_unsupported - payout_not_found - payout_not_fundable - quote_expired - bundler_rejected - bundler_unavailable - contact_details_invalid - contact_in_use - kyb_incomplete - kyb_roster_conflict - kyb_subject_conflict - document_fields_missing - document_not_found - document_type_unsupported - invalid_enum_value - entity_not_found - escrow_not_found - escrow_action_not_found - escrow_not_operated_by_you - escrow_state_changed - action_in_flight - simulation_failed - stale_nonce - amount_out_of_range - amount_not_allowed - window_closed - token_not_supported - receiver_not_a_client - rail_not_found - rail_not_available - rail_requirements_unmet - phone_required - payin_not_available - payin_expired - payin_not_found - transaction_not_found title: PlatformErrorCode CountryCode: type: string enum: - AF - AX - 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 - XK - 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 title: CountryCode description: ISO 3166-1 alpha-2 country codes. RequisiteFields: properties: iban: anyOf: - type: string - type: 'null' title: Iban description: International account identifier without display separators. bic: anyOf: - type: string - type: 'null' title: Bic description: BIC or SWIFT identifier of the destination institution. accountNumber: anyOf: - type: string - type: 'null' title: Accountnumber description: Domestic account number. routingNumber: anyOf: - type: string - type: 'null' title: Routingnumber description: Domestic routing or clearing number. pixKey: anyOf: - type: string - type: 'null' title: Pixkey description: Brazil PIX destination key. pixKeyType: anyOf: - $ref: '#/components/schemas/RequisitePixKeyType' - type: 'null' description: Type of Brazil PIX key. paymentKey: anyOf: - type: string - type: 'null' title: Paymentkey description: Local payment key required by the selected method. financialInstitutionId: anyOf: - type: string - type: 'null' title: Financialinstitutionid description: Institution identifier from the method directory. branchNumber: anyOf: - type: string - type: 'null' title: Branchnumber description: Destination institution branch identifier. accountKind: anyOf: - $ref: '#/components/schemas/RequisiteAccountKind' - type: 'null' description: Checking, savings or equivalent classification. phoneNumber: anyOf: - type: string - type: 'null' title: Phonenumber description: Phone number required by the selected local method. type: object title: RequisiteFields RequisiteHolder-Output: properties: type: $ref: '#/components/schemas/RequisiteHolderType' description: Whether the account holder is an individual or a business. firstName: anyOf: - type: string - type: 'null' title: Firstname description: Legal given name of an individual holder. lastName: anyOf: - type: string - type: 'null' title: Lastname description: Legal family name of an individual holder. businessName: anyOf: - type: string - type: 'null' title: Businessname description: Registered legal name of a business holder. address: anyOf: - $ref: '#/components/schemas/UserAddress' - type: 'null' description: Postal address of the account holder. idType: anyOf: - $ref: '#/components/schemas/RequisiteIdType' - type: 'null' description: Government identifier type for the holder. idNumber: anyOf: - type: string - type: 'null' title: Idnumber description: Government identifier number for the holder. taxId: anyOf: - type: string - type: 'null' title: Taxid description: Tax identifier of the holder. nationality: anyOf: - type: string - type: 'null' title: Nationality description: ISO country code of the holder's nationality. type: object required: - type title: RequisiteHolder BankAddress: properties: addressLine1: type: string title: Addressline1 description: Street name and building number. city: anyOf: - type: string - type: 'null' title: City description: City or locality. state: anyOf: - type: string - type: 'null' title: State description: State, province or administrative area. postalCode: anyOf: - type: string - type: 'null' title: Postalcode description: Postal or ZIP code. country: anyOf: - type: string - type: 'null' title: Country description: ISO 3166-1 alpha-2 country code. type: object required: - addressLine1 title: BankAddress IntermediaryBank: properties: bic: type: string title: Bic description: BIC or SWIFT identifier of the intermediary institution. name: anyOf: - type: string - type: 'null' title: Name description: Name of the intermediary institution. address: anyOf: - $ref: '#/components/schemas/BankAddress' - type: 'null' description: Postal address of the intermediary institution. accountNumber: anyOf: - type: string - type: 'null' title: Accountnumber description: Account number used at the intermediary institution. type: object required: - bic title: IntermediaryBank BalanceAccount: type: string enum: - USDC - EURC title: BalanceAccount RequisiteState: type: string enum: - active - pending - closed title: RequisiteState RequisitePixKeyType: type: string enum: - phone - email - tax_id - random title: RequisitePixKeyType RequisiteAccountKind: type: string enum: - checking - savings - deposit - salary - other title: RequisiteAccountKind RequisiteHolderType: type: string enum: - individual - business title: RequisiteHolderType RequisiteIdType: type: string enum: - passport - national_id - foreigner_id - temporary_permit - minor_id - driving_license - resident_card - tax_id - other title: RequisiteIdType securitySchemes: HTTPBearer: type: http scheme: bearer ````