Trusted agent

A trusted agent is a person allowed to buy on behalf of a B2B customer. Every agent belongs to exactly one customer.

At the till, the cashier picks an agent after the customer: agent search only shows the selected customer's agents, with each agent's name and whether identification is required. When the customer has requireAgent: true, the sale cannot go on without an agent. See B2B Customer in the Checkout App.

An agent record

{
  "agentId": "5f0c2a9e-8d41-4b7a-b6e2-91c3d4a7f018",
  "customerId": "0b7f6a52-3c1e-4d8f-9a63-2f5d1c7e8b40",
  "businessUnitGroup": "b2b-north",
  "externalAgentId": "A-17",
  "name": "Anna Lind",
  "requireIdentification": true,
  "phone": "+46701234567",
  "email": "anna.lind@nordbygg.example",
  "identityNumber": "ID-448812"
}

Field	Meaning
agentId	The CRS id of the agent. Generated by CRS unless you send one when the agent is created.
customerId	Required. The CRS id of the customer the agent buys for. It must be a customer that exists and is not deleted, or the request returns 404 Customer not found.
externalAgentId	Your own id for the agent. If you leave it out when the agent is created, it is set to the agentId. Fixed once set.
businessUnitGroup	Always the customer's group; see below.
requireIdentification	Whether the till shows that identification is required for this agent.
phone	An international number with country code, stored in E.164 form (+46 70-123 45 67 becomes +46701234567).
identityNumber	Free text; CRS does not check its format.

The agent also has a required name and an optional email. A field without a value is left out of the response. An agent response does not carry the customer's externalCustomerId, a status or timestamps. The API reference has the full schema.

The agent's business unit group

An agent always has its customer's business unit group. Leave businessUnitGroup out and CRS takes the customer's. If you send it and it differs from the customer's, the request returns 409 businessUnitGroup must match the customer business unit group. An agent of a customer without a group has no group either.

The group must be one CRS knows, and this is checked on every PUT /api/v1/agents, not only on create. See Business unit group.

External ids

externalAgentId is unique within its customer. Two agents of the same customer cannot share it (409 Trusted agent external key conflict); agents of different customers can.

An agent created with PUT /api/v1/agents is the same record the external ingest endpoints address with the customer's externalCustomerId and the agent's externalAgentId.

Writing an agent

PUT /api/v1/agents finds its target in this order:

1. agentId of an existing agent: updates it (200). CRS stores the customerId from the body and only checks that this customer is in the agent's group, so always send the agent's current customerId.
2. agentId that no agent has: creates the agent with that id (201).
3. agentId of a deleted agent: 404 Trusted agent not found; the agent stays deleted.
4. No agentId, but externalAgentId: looks the agent up within the customer. A match is updated (200), a deleted match is restored with its original agentId (201), and no match creates an agent (201).
5. Neither: creates an agent with a generated agentId (201).

The response is the stored agent.

PUT replaces the whole agent. requireIdentification, phone, email and identityNumber are cleared when you leave them out. Optional fields can be left out, but not sent as null (400).

On an existing agent, a different externalAgentId returns 409 externalAgentId cannot be changed on an existing trusted agent (leaving it out keeps the stored one), and a customer in another group returns 409 businessUnitGroup cannot be changed on an existing trusted agent.

PATCH /api/v1/agents/{agentId} changes name, requireIdentification, phone, email and identityNumber, and only the ones in the body. ⚠ PATCH cannot clear a field: null counts as "no change". Use PUT to remove a phone number, email or identity number. agentId, customerId, externalAgentId and businessUnitGroup cannot be patched (400).

Deleting an agent

DELETE /api/v1/agents/{agentId} answers 204. Delete is soft: the agent disappears from reads and search, and a second delete returns 404. The agent's external id stays reserved, so a PUT without agentId that sends the same externalAgentId for the same customer restores it with its original agentId (201). A PUT with the deleted agentId returns 404.

A customer cannot be deleted while it has agents that are not deleted. Delete the agents first. Agents of a deleted customer cannot be written (404 Customer not found) until the customer is restored.

Searching

GET /api/v1/agents returns agents matching all the filters you send:

Parameter	Matches
customerId	The customer's CRS id, exactly.
externalCustomerId	The customer's own id, exactly.
externalAgentId	Exactly.
name	Fuzzy and case-insensitive: close spellings match too, ranked below exact, starts-with and contains matches.
businessUnitId	The agents a business unit may see: see Search by business unit.

Page through the results with skip and take (at most 200 per page). The response is { "items": [...], "page": { "skip": 0, "take": 50, "hasMore": false } }; there is no total count. Deleted agents are never returned.

Permissions and errors

Reading needs crs.agent.read, writing and deleting crs.agent.write. On the endpoints described here, these are checked against the agent's business unit group. See Who may read and write which records.

Status	Message	When
400	one message per failed rule	The body breaks a rule above, or carries an unknown property.
403	Forbidden	You have no access to the agent's business unit group.
404	Customer not found	The customerId does not exist or the customer is deleted.
404	Trusted agent not found	The agentId does not exist or the agent is deleted.
409	businessUnitGroup must match the customer business unit group	The body's group differs from the customer's.
409	externalAgentId cannot be changed on an existing trusted agent	A different externalAgentId for an existing agent.
409	businessUnitGroup cannot be changed on an existing trusted agent	The agent's group would change.
409	Business Unit Group does not exist, or is not part of Customer Registry type	The customer's group is not known to CRS.
409	Trusted agent external key conflict	Another agent of the customer already has this externalAgentId.