Customers API

Customer operations use customers.read or customers.write and return records only from the credential's team.

Endpoints

Prefix each endpoint with the environment base URL, such as https://api.eigenn.io/v1.

List Customers

GET /customers supports:

• q text search
• sort tuple
• cursor
• pageSize from 1 to 100
• tag IDs
• country codes
• tab filters: all, first-time, repeat, recent, unpaid, or paid

The response contains data and cursor metadata. It does not include a total count.

curl --request GET \
  --url "https://api.eigenn.io/v1/customers?pageSize=25&q=acme" \
  --header "Authorization: Bearer $EIGENN_API_TOKEN"

Create or Upsert

POST /customers needs:

• name
• email

Optional fields include billing email, contact, phone, website, address, country code, VAT number, Peppol ID, note, and tags.

curl --request POST \
  --url https://api.eigenn.io/v1/customers \
  --header "Authorization: Bearer $EIGENN_API_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: customer-acme-2026-07-11" \
  --data '{
    "name": "Acme Corporation",
    "email": "[email protected]",
    "billingEmail": "[email protected]",
    "countryCode": "US"
  }'

This operation can update a customer that matches. In that case, Eigenn does not create a separate record. Examine the returned ID and fields. Do not assume every 201 response represents a brand-new business identity.

The public request schema does not advertise an arbitrary externalId or metadata object. Store joins with documented fields and the returned Eigenn customer ID.

Retrieve a Customer

GET /customers/{id} returns contact, address, finance summary, activity, engagement, and tag fields available for that customer.

A 404 means the customer does not exist or is not accessible to the authenticated team.

Update a Customer

PATCH /customers/{id} changes only the supplied fields. Omitted fields remain unchanged.

Use a new Idempotency-Key for each logical change. Eigenn does not support the reuse of a key for a different patch.

Delete a Customer

DELETE /customers/{id} returns the deleted customer on success.

Eigenn does not automatically delete the associated invoices. Examine invoice ownership and reporting effects before you remove the customer record.

Important Field Rules

• Email fields use email format validation.
• countryCode uses ISO 3166-1 alpha-2 values.
• peppolId follows the documented scheme:identifier pattern.
• Eigenn documents tags as objects with an ID and a name, not as free-form strings.
• Cursor values are opaque.

Common Errors

Related Pages

• Customer Records
• Authentication
• Pagination
• Errors