Skip to main content
POST
Contracts / Create

Authorizations

Authorization
string
header
required

OAuth2 Bearer Authorization

Scopes

crm:contracts

Headers

Accept-Language
string

BCP 47 language tag for content negotiation (e.g. en, de-DE).

Example:

"en"

Body

application/json

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.

business
boolean
default:false
required

True for B2B customers, false for private individuals. Drives required fields (company_name, VAT/tax code) and lifecycle rules.

salutation
enum<string>
required

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.

Available options:
0,
1,
2,
3,
4,
5,
6,
7,
8,
9,
10
firstname
string
required

First name of the contract holder. Required for private customers.

Maximum string length: 70
surname
string
required

Surname (last name) of the contract holder. Required for private customers.

Maximum string length: 70
street
string
required

Street name of the contract holder's primary address.

Maximum string length: 255
house_number
string
required

House number of the primary address; may contain letters or suffixes (e.g., "12a").

Maximum string length: 16
zip
string
required

Postal code of the contract holder's primary address. Length and format are validated against country_id — invalid combinations are rejected.

Maximum string length: 16
city
string
required

City of the primary address.

Maximum string length: 128
country_id
integer<int32>
required

Internal country identifier of the primary address.

billing_salutation
enum<string>
required

Salutation code for the billing recipient. Same codes and meanings as salutation (0-10).

Available options:
0,
1,
2,
3,
4,
5,
6,
7,
8,
9,
10
billing_firstname
string
required

First name of the billing recipient when different from the contract holder.

Maximum string length: 70
billing_surname
string
required

Surname of the billing recipient when different from the contract holder.

Maximum string length: 70
billing_street
string
required

Street name of the billing address when different from the contract address.

Maximum string length: 255
billing_house_number
string
required

House number of the billing address; may contain letters or suffixes (e.g., "12a").

Maximum string length: 16
billing_zip
string
required

Postal code of the billing address.

Maximum string length: 16
billing_city
string
required

City of the billing address.

Maximum string length: 128
billing_email
string
required

Email address to which invoices and billing correspondence are sent.

Maximum string length: 128
billing_phone
string
required

Phone number of the billing recipient.

Maximum string length: 128
ext_contract_id
string

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.

Maximum string length: 50
external_customer_id
string

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.

Maximum string length: 15
customer_group_id
integer<int32>

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
string

Registered company name. Required for business customers (business = true).

Maximum string length: 255
title
string

Academic or honorific title prepended to the contract holder's name (Dr., Prof., etc.).

Maximum string length: 50
date_of_birth
string<date>

Date of birth of the contract holder; relevant for private customers.

Pattern: ^\d{4}-\d{2}-\d{2}$
phone_home
string

Home phone number of the contract holder, without country or area prefix.

Maximum string length: 50
phone_home_area_code
string

Country or area dialing prefix for phone_home.

Maximum string length: 10
phone_mobile
string

Mobile phone number of the contract holder, without country or area prefix.

Maximum string length: 50
phone_mobile_area_code
string

Country or area dialing prefix for phone_mobile.

Maximum string length: 10
phone_business
string

Business/work phone number of the contract holder, without country or area prefix.

Maximum string length: 50
phone_business_area_code
string

Country or area dialing prefix for phone_business.

Maximum string length: 10
email_private
string

Private email address of the contract holder (customer-version field).

Maximum string length: 255
email_business
string

Business email address of the contract holder (customer-version field).

Maximum string length: 255
reference_field_1
string

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.

Maximum string length: 255
reference_field_2
string

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.

Maximum string length: 255
billing_company
string

Company name used on invoices when the billing recipient differs from the contract holder.

Maximum string length: 255
billing_title
string

Academic or honorific title of the billing recipient (Dr., Prof., etc.).

Maximum string length: 70
billing_country_id
integer<int32>

Internal country identifier of the billing address. Defaults to country_id when omitted on create.

auth_username
string

Username for the ChargeCloud customer-app login; must be unique per client.

Maximum string length: 255
auth_password
string

Password for the customer-app login. Write-only; never returned in responses.

Maximum string length: 128
advertising_agreement_mail
boolean
default:false

Customer consent flag for receiving marketing communication via postal mail.

advertising_agreement_phone
boolean
default:false

Customer consent flag for receiving marketing communication via phone.

advertising_agreement_email
boolean
default:false

Customer consent flag for receiving marketing communication via email.

accept_current_agb
boolean
default:false

Confirmation that the customer accepted the current AGB (terms & conditions); required in most emobility flows.

accept_current_privacy_policy
boolean
default:false

Confirmation that the customer accepted the current privacy policy; required in most emobility flows.

vat_identification_number
string

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.

Maximum string length: 50
tax_code
string

National tax code (e.g., Italian codice fiscale); alternative to vat_identification_number. Required for B2B contracts when no VAT number is supplied.

Maximum string length: 50
simulation
boolean
default:false

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
string<date>

Date on which the contract's delivery or service begins.

Pattern: ^\d{4}-\d{2}-\d{2}$
attributes
string

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.

Response

The newly created contract with its customer reference and onboarding flags (mail verification, manual confirmation).

contract
object
required

The contract record. Collections carry the list projection, single-contract responses the full view projection.

customer_id
integer<int32>

Internal numeric identifier of the customer record created or reused with the contract.

external_customer_id
string

Caller-supplied customer identifier echoed from the request. Null when the caller did not supply one.

mail_verification_needed
boolean
default:false

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
boolean
default:false

True when the contract requires manual activation by a ChargeCloud operator before it becomes binding.