Customers

Customer object

A customer represents a policy holder. The relationship between customers and policies is many-to-many: a customer can be on several policies, and a policy can have several customers, each with a business role.

General

• payment methods: a list of payment methods used by this customer.
• invoices: a list of invoices issued to this customer.

Product specific information

• custom fields: a list of product specific attributes. For more details check out custom fields.
• aggregate fields: name, role and siret are properties of the customer itself rather than custom fields, and are sent as top-level properties of the edit call.

Working with customers over the API

A customer is not created on its own during new business: POST /customers?productId=... creates the policyholder together with a policy and a branch, and returns all three. Add further parties to an existing contract with POST /customers/policies/{policyId}, each with their business role.

Fill a customer in with PATCH /customers/{customerId}.

GET /customers/{customerId}/relations lists the contracts a customer is attached to, and GET /policies/{policyId}/customers does the reverse — useful for finding which party is the payer, since that is the one whose payment method gates a signature request.

How company enrichment overwrites what you send

Company identity is the one part of a customer you do not control. You do not copy registry values onto the customer yourself: enrichment is automatic and authoritative. Supplying the field whose integration key is siret triggers a lookup in the official French company registry, and every other customer field mapped to a company-registry key — legal name, legal structure, business activity, registered address, company status — is overwritten with the registry's value, regardless of what you sent. Underwriting depends on the registry being the source of truth for company identity.

Send the SIRET, then read the customer back. The registry key list, what happens to legal statuses the registry omits, and why an invalid SIRET discards the rest of your request are in Fields the platform owns.

To let a user pick their company before you create anything, GET /siren queries the registry without touching a contract. Pass at least one of siren, siret or name — a name search returns several matches:

curl 'https://api.sandbox.korint.io/siren?siret=<siret>' \
  --header 'Authorization: Bearer <access_token>'

This route is tenant-agnostic and takes no tenant header. The response carries total and a data array of formatted company records. A malformed identifier returns INVALID_CUSTOMER_SIRET or INVALID_CUSTOMER_SIREN; a call with no query parameter at all returns REQUEST_VALIDATION_FAILED. An anonymous session may not call it (403 FORBIDDEN), which is why a public company-product funnel takes a typed SIRET and lets enrichment happen server-side on the PATCH.

Customer statuses

A customer has a simple two-status lifecycle.

Status	Allowed Operations	Next Status
CUSTOMER_CREATED	Edit your customer information.	CUSTOMER_CONFIRMED
CUSTOMER_CONFIRMED	The customer's details are confirmed. You can modify them through a Mid Term Agreement.	Can remain confirmed.