Customers API
Create, find, update, and delete team-scoped customer records through public API v1.
Customer operations use customers.read or customers.write and return records only from the credential's team.
Endpoints
| Method | Endpoint | Scope | Purpose |
|---|---|---|---|
| GET | /customers | customers.read | List and filter customers |
| POST | /customers | customers.write | Create or upsert a customer |
| GET | /customers/{id} | customers.read | Retrieve one customer |
| PATCH | /customers/{id} | customers.write | Update supplied fields |
| DELETE | /customers/{id} | customers.write | Delete a customer |
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
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
| Status | Cause |
|---|---|
| 401 | Missing or invalid bearer token |
| 403 | Missing customers.read or customers.write |
| 404 | Customer is outside the team or no longer exists |
| 409 | Request conflicts with current state |
| 422 | Request structure is invalid |
| 429 | Resource limit exceeded |