> ## Documentation Index > Fetch the complete documentation index at: https://docs.grainfinance.co/llms.txt > Use this file to discover all available pages before exploring further. # List Customers > Retrieves a list of all existing customers. ## OpenAPI ````yaml GET /customers openapi: 3.1.0 info: title: Grain API version: 1.0.0 description: >- Grain's API provides a comprehensive set of endpoints for managing hedging, spot transactions, pricing, and fund movements - enabling seamless integration of FX workflows into your platform. Each API call follows REST conventions, uses secure authentication, and returns standardized responses for consistency across environments. license: name: Creative Commons Attribution 3.0 contact: name: Grain Finance url: https://docs.grainfinance.co email: support@grainfinance.co termsOfService: https://grainfinance.co/terms-of-service/ x-apiClientRegistration: url: https://grainfinance.co/partners servers: - url: https://api.grainfinance.co/v1 description: Grain API security: [] tags: - name: Hedges description: >- Hedge objects represent transactions that lock exchange rates for future dates. A single hedge locks an exchange rate for a future transaction between two currencies. - name: Dual Hedges description: >- A dual hedge mitigates FX risk by automatically generating two linked hedge legs - a customer leg and a supplier leg - both routed through the customer's functional currency. This structure reduces exposure to currency fluctuations for both cash flow and accounting purposes, while allowing independent tracking and reporting of each hedge leg. - name: Customers description: >- Customer objects represent your end customers on the Grain platform. A customer must be created before a hedge or spot transaction can be initiated. - name: Pricing description: >- Pricing endpoints provide access to FX rates for currency pairs that are not being hedged. These endpoints can be used for live rate display or bulk retrieval to support high-volume quoting workflows. - name: Spots description: >- Spot objects represent currency conversions executed for immediate or near-term settlement. - name: Conversions description: >- Conversion objects represent currency conversions executed for immediate or near-term settlement. - name: Wallets description: Endpoints to view balances, manage funding, and perform transfers. paths: /customers: get: tags: - Customers description: Retrieves a list of all existing customers. operationId: List parameters: - description: >- external_customer_id is the customer id, as identified within your system in: query name: external_customer_id required: false schema: type: string - description: page number indicating which set of items to return in: query name: page required: false schema: $ref: '#/components/schemas/Page' - description: The number of items in a page in: query name: per_page required: false schema: $ref: '#/components/schemas/PerPage' responses: '200': description: Customer Found content: application/json: schema: $ref: '#/components/schemas/ListCustomersResponseBody' security: - api-key: [] components: schemas: Page: type: number format: double description: The page indicating which set of items are returned minimum: 1 PerPage: type: number format: double description: number of items in a page minimum: 1 maximum: 100 ListCustomersResponseBody: description: A response containing a list of customers matching the search criteria. properties: customers: items: $ref: '#/components/schemas/Customer' type: array description: A list of customers matching the search criteria. pagination: $ref: '#/components/schemas/PaginationResponse' required: - customers - pagination type: object additionalProperties: false Customer: properties: id: $ref: '#/components/schemas/UUID' description: The id of the customer within the Grain platform. example: 1b0ada1e-fa1b-4cfe-a553-01b340c5650e companyName: type: string description: The legal name of the customer's company example: Ollivander's Wand Shop companyAddress: type: string description: The address of the company example: 12 Diagon Alley companyCity: type: string description: The city of the company example: London companyState: type: string description: The state the company is in (US based) example: London companyCountry: $ref: '#/components/schemas/CountryCode' contactEmail: $ref: '#/components/schemas/ContactEmail' description: The email for the company's primary contact example: customer@company.com contactFullName: type: string description: The name of the company's primary contact example: Garrick Ollivander contactPhoneNumber: type: string description: The phone number of the company's primary contact example: '+12125551234' companyTaxId: type: string description: The tax identification or registration number of the company example: 123-45-6789 externalCustomerId: type: string description: The id used to identify the customer within your platform example: 630231b3ae0d7e9e5097ad35 status: $ref: '#/components/schemas/CustomerStatus' extraFields: $ref: '#/components/schemas/CustomersExtraFieldsParam' description: |- Additional fields that provide further details about the customer. These fields should be specified as a valid JSON object. example: field_a: value_a field_b: value_b required: - id - companyName - companyCountry - externalCustomerId - status type: object additionalProperties: false PaginationResponse: description: Pagination parameters of the returned results. properties: page: $ref: '#/components/schemas/Page' perPage: $ref: '#/components/schemas/PerPage' totalResults: type: number format: double description: The total amount of results available required: - page - perPage - totalResults type: object additionalProperties: false UUID: type: string format: uuid description: |- Stringified UUIDv4. See [RFC 4112](https://tools.ietf.org/html/rfc4122) pattern: >- [0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-4[0-9A-Fa-f]{3}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12} CountryCode: type: string example: GB description: The alpha-2 ISO 3166 country code of the entity's country. pattern: ^[A-Za-z]{2}$ ContactEmail: type: string example: garrick@ollivanders.co.uk description: The email address of the company's primary contact CustomerStatus: description: The eligibility of the customer to receive quotes enum: - Pending - Approved - Rejected type: string CustomersExtraFieldsParam: properties: {} additionalProperties: anyOf: - type: string - type: number format: double - type: boolean type: object example: field_a: value_a field_b: value_b description: |- Additional fields that provide further details about the company. These fields should be specified as a valid JSON object. securitySchemes: api-key: type: http scheme: basic description: >- Basic authentication using the partner API keys from https://console.grainfinance.co/keys ````