> ## 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 / Create > Creates a contract and its customer record in one call and returns the contract with onboarding flags. Set `simulation = true` to validate the input without persisting. Required permission: crm:contracts:create. Available contexts: API Key. ## OpenAPI ````yaml /api/core-api/crmiapi.json post /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: post: tags: - Contracts summary: Contracts / Create description: >- Creates a contract and its customer record in one call and returns the contract with onboarding flags. Set `simulation = true` to validate the input without persisting. Required permission: crm:contracts:create. Available contexts: API Key. operationId: /api/v1/crm/contracts_POST parameters: - 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 requestBody: description: >- Creates a contract and its customer record in one call and returns the contract with onboarding flags. Set `simulation = true` to validate the input without persisting. Required permission: crm:contracts:create. Available contexts: API Key. content: application/json: schema: type: object required: - business - salutation - firstname - surname - street - house_number - zip - city - country_id - billing_salutation - billing_firstname - billing_surname - billing_street - billing_house_number - billing_zip - billing_city - billing_email - billing_phone properties: ext_contract_id: type: string maxLength: 50 description: >- Contract identifier as known by an external CRM. This is the primary field used to match ChargeCloud contracts to records in upstream systems (EDI feeds, partner integrations, migrations). Max 50 chars. external_customer_id: type: string maxLength: 15 description: >- Caller-supplied identifier used to link the customer to an external CRM record. Validation rules can differ per customer group (regex / prefix), so the same value may be accepted for one customer group and rejected for another. Max 15 chars. 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. customer_group_id: type: integer format: int32 description: >- Customer group the customer is assigned to (pricing tier or reporting cohort). Resolved via the customer's group association; not stored on the contract itself. company_name: type: string maxLength: 255 description: >- Registered company name. Required for business customers (business = true). title: type: string maxLength: 50 description: >- Academic or honorific title prepended to the contract holder's name (Dr., Prof., etc.). salutation: type: string enum: - '0' - '1' - '2' - '3' - '4' - '5' - '6' - '7' - '8' - '9' - '10' description: >- Salutation code for the contract holder. Codes: 1 Mr, 2 Mrs, 3 Family, 4 Mr and Mrs, 5 Mrs and Mrs, 6 Mr and Mr, 7 married couple, 8 Company, 9 none, 10 diverse; 0 is the unset placeholder. New private/business registrations only accept 1, 2, 3 and 8. 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. street: type: string maxLength: 255 description: Street name of the contract holder's primary address. house_number: type: string maxLength: 16 description: >- House number of the primary address; may contain letters or suffixes (e.g., "12a"). 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. country_id: type: integer format: int32 description: Internal country identifier of the primary address. date_of_birth: type: string format: date pattern: ^\d{4}-\d{2}-\d{2}$ description: >- Date of birth of the contract holder; relevant for private customers. phone_home: type: string maxLength: 50 description: >- Home phone number of the contract holder, without country or area prefix. phone_home_area_code: type: string maxLength: 10 description: Country or area dialing prefix for phone_home. phone_mobile: type: string maxLength: 50 description: >- Mobile phone number of the contract holder, without country or area prefix. phone_mobile_area_code: type: string maxLength: 10 description: Country or area dialing prefix for phone_mobile. phone_business: type: string maxLength: 50 description: >- Business/work phone number of the contract holder, without country or area prefix. phone_business_area_code: type: string maxLength: 10 description: Country or area dialing prefix for phone_business. email_private: type: string maxLength: 255 description: >- Private email address of the contract holder (customer-version field). email_business: type: string maxLength: 255 description: >- Business email address of the contract holder (customer-version field). reference_field_1: type: string maxLength: 255 description: >- Free-text client-configurable reference. Common use cases include TecDoc identifiers, HC (Hauptkunde) numbers, cost centres, purchase-order numbers, and project IDs. No semantic enforcement by the system. reference_field_2: type: string maxLength: 255 description: >- Second free-text client-configurable reference, parallel to reference_field_1. Same use cases (TecDoc, HC, cost centres, etc.) — provided as a second slot when one reference is not enough. billing_company: type: string maxLength: 255 description: >- Company name used on invoices when the billing recipient differs from the contract holder. billing_salutation: type: string enum: - '0' - '1' - '2' - '3' - '4' - '5' - '6' - '7' - '8' - '9' - '10' description: >- Salutation code for the billing recipient. Same codes and meanings as salutation (0-10). billing_title: type: string maxLength: 70 description: >- Academic or honorific title of the billing recipient (Dr., Prof., etc.). billing_firstname: type: string maxLength: 70 description: >- First name of the billing recipient when different from the contract holder. billing_surname: type: string maxLength: 70 description: >- Surname of the billing recipient when different from the contract holder. billing_street: type: string maxLength: 255 description: >- Street name of the billing address when different from the contract address. billing_house_number: type: string maxLength: 16 description: >- House number of the billing address; may contain letters or suffixes (e.g., "12a"). billing_zip: type: string maxLength: 16 description: Postal code of the billing address. billing_city: type: string maxLength: 128 description: City of the billing address. billing_country_id: type: integer format: int32 description: >- Internal country identifier of the billing address. Defaults to country_id when omitted on create. billing_email: type: string maxLength: 128 description: >- Email address to which invoices and billing correspondence are sent. billing_phone: type: string maxLength: 128 description: Phone number of the billing recipient. auth_username: type: string maxLength: 255 description: >- Username for the ChargeCloud customer-app login; must be unique per client. auth_password: type: string maxLength: 128 description: >- Password for the customer-app login. Write-only; never returned in responses. advertising_agreement_mail: type: boolean default: false description: >- Customer consent flag for receiving marketing communication via postal mail. advertising_agreement_phone: type: boolean default: false description: >- Customer consent flag for receiving marketing communication via phone. advertising_agreement_email: type: boolean default: false description: >- Customer consent flag for receiving marketing communication via email. accept_current_agb: type: boolean default: false description: >- Confirmation that the customer accepted the current AGB (terms & conditions); required in most emobility flows. accept_current_privacy_policy: type: boolean default: false description: >- Confirmation that the customer accepted the current privacy policy; required in most emobility flows. vat_identification_number: type: string maxLength: 50 description: >- VAT identification number of the business customer. Required for B2B contracts unless a `tax_code` is supplied instead. Format and check-digit rules apply per country (e.g. DE: "DE" + 9 digits, IT: 11 digits) — invalid values are rejected with HTTP 422. tax_code: type: string maxLength: 50 description: >- National tax code (e.g., Italian codice fiscale); alternative to vat_identification_number. Required for B2B contracts when no VAT number is supplied. simulation: type: boolean default: false description: >- When true, the contract is fully validated and the same response shape is returned, but nothing is saved and no follow-up actions (notifications, downstream sync, emails) are triggered. Use this to pre-validate customer input before the real submission. start_date: type: string format: date pattern: ^\d{4}-\d{2}-\d{2}$ description: Date on which the contract's delivery or service begins. attributes: type: string description: >- JSON-encoded map of contract attributes (e.g. `{"attribute_key":"value", ...}`). Keys and value types are configured per client — see the Attributes API for the available set. Unknown keys are rejected; optional attributes fall back to their configured default when omitted. required: true responses: '201': 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: - contract properties: contract: type: object properties: 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). 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. ordered_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 customer ordered the contract; may differ from created_at when the order predates data entry. 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. modification_date: 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 of the last modification to the contract record. 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. billing_blocked: type: boolean default: false description: >- True when automatic billing is currently suspended for this contract. dunning_locked: type: boolean default: false description: >- True when dunning (collection) processes are paused for this contract. ext_contract_id: type: string maxLength: 50 description: >- Contract identifier as known by an external CRM. This is the primary field used to match ChargeCloud contracts to records in upstream systems (EDI feeds, partner integrations, migrations). Max 50 chars. external_id: type: string maxLength: 15 description: >- Contract-level external identifier (max 15 chars). Use ext_contract_id for longer references. customer_group_id: type: integer format: int32 description: >- Customer group the customer is assigned to (pricing tier or reporting cohort). Resolved via the customer's group association; not stored on the contract itself. account_id: type: integer format: int32 description: >- Reference to the financial ledger (accounts) tracking debits, credits, invoices, and payments. Every contract has exactly one account. 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). salutation: type: string enum: - '0' - '1' - '2' - '3' - '4' - '5' - '6' - '7' - '8' - '9' - '10' description: >- Salutation code for the contract holder. Codes: 1 Mr, 2 Mrs, 3 Family, 4 Mr and Mrs, 5 Mrs and Mrs, 6 Mr and Mr, 7 married couple, 8 Company, 9 none, 10 diverse; 0 is the unset placeholder. New private/business registrations only accept 1, 2, 3 and 8. 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. street: type: string maxLength: 255 description: Street name of the contract holder's primary address. house_number: type: string maxLength: 16 description: >- House number of the primary address; may contain letters or suffixes (e.g., "12a"). 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. country_id: type: integer format: int32 description: Internal country identifier of the primary address. phone: type: string maxLength: 255 description: >- Aggregated contract-level phone number; detailed numbers live on phone_home, phone_mobile, phone_business. email: type: string maxLength: 255 description: >- Aggregated contract-level email; distinct from email_private and email_business on the customer version. reference_field_1: type: string maxLength: 255 description: >- Free-text client-configurable reference. Common use cases include TecDoc identifiers, HC (Hauptkunde) numbers, cost centres, purchase-order numbers, and project IDs. No semantic enforcement by the system. reference_field_2: type: string maxLength: 255 description: >- Second free-text client-configurable reference, parallel to reference_field_1. Same use cases (TecDoc, HC, cost centres, etc.) — provided as a second slot when one reference is not enough. billing_company: type: string maxLength: 255 description: >- Company name used on invoices when the billing recipient differs from the contract holder. billing_salutation: type: string enum: - '0' - '1' - '2' - '3' - '4' - '5' - '6' - '7' - '8' - '9' - '10' description: >- Salutation code for the billing recipient. Same codes and meanings as salutation (0-10). billing_title: type: string maxLength: 70 description: >- Academic or honorific title of the billing recipient (Dr., Prof., etc.). billing_firstname: type: string maxLength: 70 description: >- First name of the billing recipient when different from the contract holder. billing_surname: type: string maxLength: 70 description: >- Surname of the billing recipient when different from the contract holder. billing_street: type: string maxLength: 255 description: >- Street name of the billing address when different from the contract address. billing_house_number: type: string maxLength: 16 description: >- House number of the billing address; may contain letters or suffixes (e.g., "12a"). billing_zip: type: string maxLength: 16 description: Postal code of the billing address. billing_city: type: string maxLength: 128 description: City of the billing address. billing_country_id: type: integer format: int32 description: >- Internal country identifier of the billing address. Defaults to country_id when omitted on create. billing_email: type: string maxLength: 128 description: >- Email address to which invoices and billing correspondence are sent. billing_phone: type: string maxLength: 128 description: Phone number of the billing recipient. title: type: string maxLength: 50 description: >- Academic or honorific title prepended to the contract holder's name (Dr., Prof., etc.). tax_code: type: string maxLength: 50 description: >- National tax code (e.g., Italian codice fiscale); alternative to vat_identification_number. Required for B2B contracts when no VAT number is supplied. external_customer_id: type: string maxLength: 15 description: >- Caller-supplied identifier used to link the customer to an external CRM record. Validation rules can differ per customer group (regex / prefix), so the same value may be accepted for one customer group and rejected for another. Max 15 chars. auth_enabled: type: boolean default: false description: >- True when the contract holder may log into the ChargeCloud customer app. auth_username: type: string maxLength: 255 description: >- Username for the ChargeCloud customer-app login; must be unique per client. phone_home: type: string maxLength: 50 description: >- Home phone number of the contract holder, without country or area prefix. phone_home_area_code: type: string maxLength: 10 description: Country or area dialing prefix for phone_home. phone_mobile: type: string maxLength: 50 description: >- Mobile phone number of the contract holder, without country or area prefix. phone_mobile_area_code: type: string maxLength: 10 description: Country or area dialing prefix for phone_mobile. phone_business: type: string maxLength: 50 description: >- Business/work phone number of the contract holder, without country or area prefix. phone_business_area_code: type: string maxLength: 10 description: Country or area dialing prefix for phone_business. email_private: type: string maxLength: 255 description: >- Private email address of the contract holder (customer-version field). email_business: type: string maxLength: 255 description: >- Business email address of the contract holder (customer-version field). advertising_agreement_mail: type: boolean default: false description: >- Customer consent flag for receiving marketing communication via postal mail. advertising_agreement_phone: type: boolean default: false description: >- Customer consent flag for receiving marketing communication via phone. advertising_agreement_email: type: boolean default: false description: >- Customer consent flag for receiving marketing communication via email. required: - uuid - type - blocked - disabled - billing_blocked - dunning_locked - account_id - business - salutation - firstname - surname - street - house_number - zip - city - phone - email - billing_salutation - billing_firstname - billing_surname - billing_street - billing_house_number - billing_zip - billing_city - billing_email - billing_phone description: >- The contract record. Collections carry the list projection, single-contract responses the full view projection. customer_id: type: integer format: int32 description: >- Internal numeric identifier of the customer record created or reused with the contract. external_customer_id: type: string description: >- Caller-supplied customer identifier echoed from the request. Null when the caller did not supply one. mail_verification_needed: type: boolean default: false description: >- True when the contract holder must verify their email before activation. The caller is expected to trigger the verification flow out of band. contract_confirmation_needed: type: boolean default: false description: >- True when the contract requires manual activation by a ChargeCloud operator before it becomes binding. description: >- The newly created contract with its customer reference and onboarding flags (mail verification, manual confirmation). '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 '500': 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: Internal server error security: - bearer: - crm:contracts components: securitySchemes: bearer: type: http description: OAuth2 Bearer Authorization scheme: bearer bearerFormat: JWT ```` ## Related topics - [Locations / Create](https://chargecloud.dev/api-reference/locations/locations-create.md) - [Contracts / Update](https://chargecloud.dev/api-reference/contracts/contracts-update.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.