> ## Documentation Index > Fetch the complete documentation index at: https://chargecloud.dev/llms.txt > Use this file to discover all available pages before exploring further. # Contracts / List > Lists contracts owned by the authenticated client, paginated and filterable by customer number, name, external contract ID, and lifecycle status. Required permission: crm:contracts:list. Available contexts: API Key. ## OpenAPI ````yaml /api/core-api/crmiapi.json get /api/v1/crm/contracts openapi: 3.2.0 info: title: chargecloud - Core API summary: chargecloud Core API. All around CRM, Asset Management and more. version: 1.141.0 description: chargecloud Core API. All around CRM, Asset Management and more. servers: - url: https://api.chargecloud.dev description: Production - chargecloud Core API - url: https://demo.chargecloud.de description: Sandbox/Dev - chargecloud Core API security: [] paths: /api/v1/crm/contracts: get: tags: - Contracts summary: Contracts / List description: >- Lists contracts owned by the authenticated client, paginated and filterable by customer number, name, external contract ID, and lifecycle status. Required permission: crm:contracts:list. Available contexts: API Key. operationId: /api/v1/crm/contracts_GET parameters: - name: customerNumber in: query description: Customer-number filter; partial, case-insensitive match. required: false schema: type: string description: Customer-number filter; partial, case-insensitive match. - name: name in: query description: >- Partial, case-insensitive match against the contract holder's firstname, surname, or company name. required: false schema: type: string description: >- Partial, case-insensitive match against the contract holder's firstname, surname, or company name. - name: extContractId in: query description: >- Filters by the upstream-system contract identifier (EDI feed, partner integration, migration import). required: false schema: type: string description: >- Filters by the upstream-system contract identifier (EDI feed, partner integration, migration import). - name: status in: query description: >- Filters by contract lifecycle status; omit to return any status. Allowed values: open (created, not yet started); cancellation_previous (cancellation sent to previous provider, energy only); delivery_net (registered with distribution network operator, energy only); waiting (approved, awaiting delivery start); active (delivery in progress); blocked (frozen, no state changes); terminated (cancelled, end date set); expired (end date passed); cancelled (annulled before becoming active); done (completed). Not every value applies to every contract type. required: false schema: type: string enum: - open - cancellation_previous - delivery_net - waiting - active - blocked - terminated - expired - done - cancelled description: >- Filters by contract lifecycle status; omit to return any status. Allowed values: open (created, not yet started); cancellation_previous (cancellation sent to previous provider, energy only); delivery_net (registered with distribution network operator, energy only); waiting (approved, awaiting delivery start); active (delivery in progress); blocked (frozen, no state changes); terminated (cancelled, end date set); expired (end date passed); cancelled (annulled before becoming active); done (completed). Not every value applies to every contract type. - name: limit in: query description: Maximum number of items per page. Maximum value is 25. required: false schema: type: integer format: int64 minimum: 1 maximum: 25 description: Maximum number of items per page. Maximum value is 25. example: '10' - name: page in: query description: Page number to retrieve (starting from 1). required: false schema: type: integer format: int64 minimum: 1 description: Page number to retrieve (starting from 1). example: '1' - name: Accept-Language in: header description: BCP 47 language tag for content negotiation (e.g. en, de-DE). required: false schema: type: string description: BCP 47 language tag for content negotiation (e.g. en, de-DE). example: en responses: '200': headers: Content-Language: description: The locale of the response content (BCP 47 language tag). required: false schema: type: string example: en content: application/json: schema: type: object required: - contracts properties: contracts: type: array items: type: object properties: id: type: integer format: int32 description: >- Internal numeric identifier of the contract. Prefer the UUID for new integrations. uuid: type: string maxLength: 36 description: Globally unique identifier of the contract. type: type: string enum: - energy - energy_external - energy_external_lima - emobility - emobility_adhoc - non_commodity description: >- Contract category. Allowed values: energy (electricity or gas supply); energy_external (external energy supplier, SHELL-imported); energy_external_lima (external contract from LIMA); emobility (EV charging with recurring billing); emobility_adhoc (one-off EV charging, no recurring contract); non_commodity (EV charging services without energy commodity). energy: type: string enum: - electricity - gas description: >- Energy product delivered. Allowed values: electricity, gas. Only relevant for energy contracts. customer_number: type: string maxLength: 50 description: >- Customer identifier assigned by the client; unique per client. business: type: boolean default: false description: >- True for B2B customers, false for private individuals. Drives required fields (company_name, VAT/tax code) and lifecycle rules. company_name: type: string maxLength: 255 description: >- Registered company name. Required for business customers (business = true). firstname: type: string maxLength: 70 description: >- First name of the contract holder. Required for private customers. surname: type: string maxLength: 70 description: >- Surname (last name) of the contract holder. Required for private customers. created_at: type: string format: date-time pattern: >- ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(Z|[+-]\d{2}:\d{2})$ description: Timestamp when the contract record was created. start_date: type: string format: date pattern: ^\d{4}-\d{2}-\d{2}$ description: >- Date on which the contract's delivery or service begins. end_date: type: string format: date pattern: ^\d{4}-\d{2}-\d{2}$ description: >- Date on which the contract's delivery or service ends. Set by the cancellation flow; null for open-ended contracts. cancelled_at: type: string format: date-time pattern: >- ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(Z|[+-]\d{2}:\d{2})$ description: >- Timestamp when the cancellation was registered. Null when not cancelled. status: type: string enum: - open - cancellation_previous - delivery_net - waiting - active - blocked - terminated - expired - done - cancelled description: >- Contract lifecycle status. Allowed values: open (created, not yet started); cancellation_previous (cancellation sent to previous provider, energy only); delivery_net (registered with distribution network operator, energy only); waiting (approved, awaiting delivery start); active (delivery in progress); blocked (frozen, no state changes); terminated (cancelled, end date set); expired (end date passed); cancelled (annulled before becoming active); done (completed). Not every value applies to every contract type. blocked: type: boolean default: false description: >- True when the contract is blocked and cannot transition to new states. disabled: type: boolean default: false description: >- True when the contract has been deactivated by an operator; excluded from charging and billing until re-enabled. usage: type: integer format: int32 description: >- Estimated yearly energy consumption in kWh used as forecast input for tariff calculation. Not live usage. zip: type: string maxLength: 16 description: >- Postal code of the contract holder's primary address. Length and format are validated against `country_id` — invalid combinations are rejected. city: type: string maxLength: 128 description: City of the primary address. required: - id - uuid - type - energy - business - firstname - surname - blocked - disabled - usage - zip - city description: >- The contract record. Collections carry the list projection, single-contract responses the full view projection. description: >- Contracts on this page; empty array when no contracts match the filters. pagination: type: object properties: page: type: integer format: int64 description: Current page number (starting from 1). example: '1' total_pages: type: integer format: int64 description: Total number of available pages. example: '5' page_size: type: integer format: int64 description: Number of items returned per page. example: '10' has_more: type: boolean default: true description: >- Indicates whether more pages are available after the current page. example: 'true' description: Pagination description: Paginated page of contracts in list-mode projection. '401': headers: Content-Language: description: The locale of the response content (BCP 47 language tag). required: false schema: type: string example: en content: application/json: schema: type: object required: - error properties: error: type: string description: Error message description: Unauthorized '403': headers: Content-Language: description: The locale of the response content (BCP 47 language tag). required: false schema: type: string example: en content: application/json: schema: type: object required: - error properties: error: type: string description: Error message description: Forbidden '405': headers: Content-Language: description: The locale of the response content (BCP 47 language tag). required: false schema: type: string example: en content: application/json: schema: type: object required: - error properties: error: type: string description: Error message description: Method not allowed '422': headers: Content-Language: description: The locale of the response content (BCP 47 language tag). required: false schema: type: string example: en content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object properties: errorKey: type: string description: A key identifying the error message: type: string description: The error message parameter: type: string description: The parameter that caused the error, if any required: - errorKey - message - parameter description: Error description: List of errors description: Request validation failed security: - bearer: - crm:contracts components: securitySchemes: bearer: type: http description: OAuth2 Bearer Authorization scheme: bearer bearerFormat: JWT ```` ## Related topics - [Locations / List](https://chargecloud.dev/api-reference/locations/locations-list.md) - [Contracts / Cancel](https://chargecloud.dev/api-reference/contracts/contracts-cancel.md) - [Contracts / Read](https://chargecloud.dev/api-reference/contracts/contracts-read.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.