> ## Documentation Index > Fetch the complete documentation index at: https://docs.spirii.com/llms.txt > Use this file to discover all available pages before exploring further. # Get v2customers > Retrieves a paginated list of customers based on the provided filter criteria. ## OpenAPI ````yaml /openapi/integration-api-v2/openapi.yaml get /v2/customers openapi: 3.0.0 info: title: Spirii API description: Spirii API version: 2.10.0 contact: {} servers: - url: https://api.spirii.com security: [] tags: [] paths: /v2/customers: get: tags: - Customer v2 - Customers v2 description: >- Retrieves a paginated list of customers based on the provided filter criteria. operationId: getCustomerList parameters: - name: limit required: false in: query description: Filter the total amount of items returned. schema: default: 50 type: integer - name: offset required: false in: query description: Skip the first N items in the result set. schema: default: 0 type: integer - name: sortBy required: false in: query description: >- When set, returned customers will be sorted by one of the available properties, descending if not otherwise specified by sortDirection. When used with `createdAt*` default is createdAt. When used with `updatedAt*` default is updatedAt (even if combined with `createdAt*`). schema: default: id enum: - id - name - type - ownerName - cpoName - createdAt - updatedAt type: string - name: sortDirection required: false in: query description: >- When set, returned customers will be sorted either descending or ascending. When used with `createdAtFrom` or `updateAtFrom`, default is `asc`. schema: default: desc enum: - desc - asc type: string - name: search required: false in: query description: Search across customer names and IDs. This includes `externalId`. schema: type: string - name: customerIds required: false in: query description: >- Ids of the customers to return. Other filters (and permissions requirement) will still apply. schema: type: array items: type: integer - name: types required: false in: query description: Types of the customers to filter. Multiple types can be selected. schema: type: array items: type: string enum: - Private - Business - CPO - CPOSubsidiary - name: ownerId required: false in: query description: >- ID of the owner of the customer, also known as parent. This will return direct descendant of the provided customer ID. Only available for filtering if you are the owner or have appropriate permissions. schema: type: integer - name: ownedBy required: false in: query description: >- ID of the owner of the customer, also known as parent. This will return all customers owned by this ownerId. Only available for filtering if you are the owner or have appropriate permissions. schema: type: integer - name: cpoId required: false in: query description: >- ID of the CPO above the customer, also known as Operator. Only available for filtering if you are the CPO or have appropriate permissions. schema: type: integer - name: createdAt required: false in: query description: Creation date of the customer. schema: type: string format: date-time - name: createdAtFrom required: false in: query description: >- Start date for filtering by creation date. When set, filter `sortBy` defaults to `createdAt`. schema: type: string format: date-time - name: createdAtTo required: false in: query description: >- End date for filtering by creation date. When set, filter `sortBy` defaults to `createdAt`. schema: type: string format: date-time - name: updatedAt required: false in: query description: Last update date of the customer. schema: type: string format: date-time - name: updatedAtFrom required: false in: query description: >- Start date for filtering by last update date. When set, filter `sortBy` defaults to `updatedAt`. schema: type: string format: date-time - name: updatedAtTo required: false in: query description: >- End date for filtering by last update date. When set, filter `sortBy` defaults to `updatedAt`. schema: type: string format: date-time responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/CustomerListResponseDTO' '400': description: Bad Request. An explanation message will be provided. '401': description: >- Unauthorized. The requested operation cannot be performed with the current access permissions. '403': description: >- Forbidden. Your credentials are missing or not valid. An explanation message will be provided. '500': description: >- An unexpected error occurred on the server while processing the request. '502': description: The request failed due to an error in an upstream service. security: - Authorization: [] components: schemas: CustomerListResponseDTO: type: object properties: data: description: Array of Customer objects. type: array items: $ref: '#/components/schemas/CustomerResponseDTO' count: type: integer description: Total count of customers. limit: type: integer description: Limit of customers per page. offset: type: integer description: Offset for pagination. required: - data - count - limit - offset CustomerResponseDTO: type: object properties: name: type: string description: The complete name of the customer. example: John Smith maxLength: 80 externalId: type: string description: >- This field can be used as a reference to your own system, e.g. an internal customer number. example: CU-12345 maxLength: 40 nullable: true country: type: string description: The country of the billing address. example: DK maxLength: 2 minLength: 2 nullable: true contactDetails: description: >- The contact details of the person who can be contacted regarding any concerns about this customer. nullable: true allOf: - $ref: '#/components/schemas/ContactDetails' payoutInformation: description: >- The payout information of the customer. It's important to pass this information if you use Spirii financial services. This ensures correct invoicing. nullable: true allOf: - $ref: '#/components/schemas/PayoutInformation' billingDetails: description: >- The billing details of the customer. It's important to pass this information if you use Spirii financial services. nullable: true allOf: - $ref: '#/components/schemas/BillingDetailsResponse' financialSetup: description: >- This financial setup ensures the customer receives accurate invoices in the correct language and currency, and on time. nullable: true allOf: - $ref: '#/components/schemas/FinancialSetup' billingSettings: description: The billing settings of the customer. nullable: true allOf: - $ref: '#/components/schemas/CustomerBillingSettings' receiptSettings: description: The receipt settings of the customer. nullable: true allOf: - $ref: '#/components/schemas/CustomerReceiptSettings' isTaxableDealer: type: boolean description: >- Whether the customer is registered as a taxable dealer. Used for tax handling. Manageable by Spirii admins only. example: false default: false id: type: integer description: The unique identifier of the customer. example: 123 owner: description: The owner of the customer. allOf: - $ref: '#/components/schemas/OwnerDto' type: type: string description: The type of customer. You can create private and business customers. enum: - Private - Business - CPO - CPOSubsidiary cpo: description: The CPO of the customer. allOf: - $ref: '#/components/schemas/CpoDto' locations: type: array description: The location IDs associated with the customer. example: - 1 - 2 - 3 items: type: integer createdAt: format: date-time type: string description: The creation date of the customer. updatedAt: format: date-time type: string description: The last update date of the customer. required: - name - contactDetails - billingDetails - id - type - cpo - locations - createdAt - updatedAt ContactDetails: type: object properties: name: type: string description: The full name of the contact person. example: John Smith email: type: string description: The email address of the contact person. example: john.smith@email.com format: email phone: type: string description: The phone number of the contact person, in ITU-T E.164 standard. externalDocs: description: External source for ITU-T E.164 url: https://en.wikipedia.org/wiki/E.164 example: +11 22 33 44 format: phone-number nullable: true required: - name - email PayoutInformation: type: object properties: iban: type: string description: >- The IBAN number. It is required when the customer is not `type=private`, its CPO (or operator) has subscribed to financial services with Spirii and country is not Denmark. example: DK5000400440116243 swiftCode: type: string description: >- The SWIFT code. It is required when the customer is not `type=private`, its CPO (or operator) has subscribed to financial services with Spirii and country is not Denmark. example: ROYCCAT2XXX bankAccountHolderName: type: string description: >- The name of the bank account holder. It is required when the customer is not `type=private` and its CPO (or operator) has subscribed to financial services with Spirii. example: John Smith maxLength: 50 minLength: 1 bankRegistrationNumber: type: string description: >- The bank registration number - only applies in Denmark. It is required when the customer is not `type=private`, its CPO (or operator) has subscribed to financial services with Spirii and selected country is Denmark. example: '1234' maxLength: 4 minLength: 4 bankAccount: type: string description: >- The bank account number - only applies in Denmark. It is required when the customer is not `type=private`, its CPO (or operator) has subscribed to financial services with Spirii and selected country is Denmark. example: '1234567890' maxLength: 10 minLength: 10 BillingDetailsResponse: type: object properties: invoiceFormat: type: string description: The invoice format can be email or GLN number. example: Email enum: - GLN - Email default: Email gln: type: string description: >- The GLN number - only applies to business customers. This is required when invoiceFormat is `GLN`. example: '0799439112768' invoiceEmail: type: string description: >- The email address where the invoices need to be sent. This is required when invoiceFormat is `Email`. example: john.smith@email.com format: email vatNumber: type: string description: >- The VAT number only applies for business customers. It is required when the customer is not `type=private` and its CPO (or operator) has subscribed to financial services with Spirii. example: '87687766' minLength: 2 maxLength: 15 address: type: string description: The street and street number of the billing the address. example: Street Avenue, 123 address2: type: string description: >- The secondary line of the billing address (e.g. apartment, suite, floor). example: Apt. 4B nullable: true city: type: string description: The city of the billing address. example: Copenhagen zipCode: type: string description: The ZIP code of the billing address. example: '2300' paymentMethod: type: string description: The default payment for payouts method is invoice. default: Invoice enum: - Invoice - Credit Card required: - paymentMethod FinancialSetup: type: object properties: language: type: string description: >- The language code (in ISO 639-1 standard) that defines the language of the invoice document. enum: - EN - DA - DE default: EN format: iso-639-1 currency: type: string description: >- The currency code defines the currency of the invoices. Must be in ISO-4217 format. It is required when the customer is not `type=private` and its CPO (or operator) has subscribed to financial services with Spirii. example: EUR format: iso-4217 minLength: 3 maxLength: 3 paymentTerms: type: string description: The payment terms define the frequency of the invoices. enum: - 2 Days - 8 Days - 14 Days - 21 Days - 30 Days - 60 Days - Current Month + 30 Days CustomerBillingSettings: type: object properties: companyCarReimbursementMethod: type: string description: The company car reimbursement method. enum: - MANUAL - PPS - SPIRII default: MANUAL companyCarKYCStatus: type: string description: >- Status of the 'Know Your Customer' process for Company Car related services enum: - InProgress - Passed - Failed chargeKeyDocumentAggregation: type: string description: Charge key document aggregation. enum: - customer - key chargeKeyLineAggregation: type: string description: Charge key line aggregation. enum: - key_and_location - key - location cpmsRevenueSharingUnit: type: string description: The type of CPMS revenue share (currency or percentage). enum: - currency - percentage cpmsRevenueSharingRate: type: number description: >- The CPMS revenue share rate. Must be a value between 0 and 1. For percentage type, 0.15 means 15%. example: 0.15 minimum: 0 maximum: 1 cpmsRevenueSharingCurrency: type: string description: The currency code for CPMS revenue sharing (e.g. EUR, SEK). example: EUR cpmsRevenueSharingEnabled: type: boolean description: Enable or disable CPMS revenue sharing for this customer. example: true default: false CustomerReceiptSettings: type: object properties: customText: type: string description: Custom text to display on receipts for this customer. maxLength: 200 OwnerDto: type: object properties: id: type: integer description: The unique identifier of the owner. example: 234 name: type: string description: The name of the owner. example: Company Inc. required: - id - name CpoDto: type: object properties: id: type: integer description: The unique identifier of the CPO (Charge Point Operator). example: 123 name: type: string description: The name of the CPO (Charge Point Operator) for this customer. example: Charge Point Operator Inc. maxLength: 80 required: - id - name securitySchemes: Authorization: type: apiKey in: header name: Authorization description: '`Authorization: Bearer `' ````