Customers Get by Id

Get Customer — GET /customers/v1/{customerId}

Sample Dataset

The examples in this file — and in the other customers examples — reuse the same small dataset: one organization and three contacts who buy under it.

Label	customerId	customerType	Notes
Organization Rubber Duck Enterprises	22222222-2222-2222-2222-222222222222	Organization	B2B account. Full organizationData on record.
Contact Ada	11111111-1111-1111-1111-111111111111	Person	Full record — email, mobile, address all present.
Contact Grace	33333333-3333-3333-3333-333333333333	Person	No country on record — comes back as "".
Contact Alan	44444444-4444-4444-4444-444444444444	Person	Minimal record — no email, mobile, or address.

Ada, Grace, and Alan all buy under Rubber Duck Enterprises — see Customers Get Organization and Customers Get Contacts for the relationship views.

---

Success Scenarios

Full Person Record

Every optional field is on record.

Request

GET /customers/v1/11111111-1111-1111-1111-111111111111
Authorization: ******
Ocp-Apim-Subscription-Key: <subscription_key>

Response — 200 OK

{
  "customer": {
    "customerId": "11111111-1111-1111-1111-111111111111",
    "name": "Ada Lovelace",
    "email": "ada.lovelace@example.com",
    "mobile": "91234567",
    "customerType": "Person",
    "isB2B": false,
    "isPublic": true,
    "country": "NO",
    "primaryAddress": {
      "streetLine1": "Enigmavegen 1",
      "postalCode": "0001",
      "city": "Oslo",
      "country": "NO"
    }
  }
}

---

Minimal Person Record — Optional Fields Omitted

Alan has no email, mobile, or address on record. Those fields are absent from the payload, not null. organizationNumber and organizationData are likewise absent — they only ever appear on an Organization record.

Request

GET /customers/v1/44444444-4444-4444-4444-444444444444
Authorization: ******
Ocp-Apim-Subscription-Key: <subscription_key>

Response — 200 OK

{
  "customer": {
    "customerId": "44444444-4444-4444-4444-444444444444",
    "name": "Alan Turing",
    "customerType": "Person",
    "isB2B": false,
    "isPublic": true,
    "country": "GB"
  }
}

Key points:

• email, mobile, and primaryAddress are omitted — checking "email" in response (or the language equivalent) is the correct way to detect “not on record,” not comparing to null
• This is the shape you should expect for the majority of Person customers

---

country Not on Record — Empty String, Never Omitted

Grace has no country on record. Unlike email/mobile/primaryAddress, country is never omitted — it comes back as "". The same rule applies to name and customerType.

Request

GET /customers/v1/33333333-3333-3333-3333-333333333333
Authorization: ******
Ocp-Apim-Subscription-Key: <subscription_key>

Response — 200 OK

{
  "customer": {
    "customerId": "33333333-3333-3333-3333-333333333333",
    "name": "Grace Hopper",
    "email": "grace.hopper@example.com",
    "customerType": "Person",
    "isB2B": false,
    "isPublic": true,
    "country": ""
  }
}

Key points:

• country: "" means “we have no country on record” — not an error, and not the same as the field being omitted
• See Conventions for the full list of fields that are never omitted

---

B2B Organization Record

Rubber Duck Enterprises has organizationNumber and a fully populated organizationData block. Both are only ever present when customerType is "Organization".

Request

GET /customers/v1/22222222-2222-2222-2222-222222222222
Authorization: ******
Ocp-Apim-Subscription-Key: <subscription_key>

Response — 200 OK

{
  "customer": {
    "customerId": "22222222-2222-2222-2222-222222222222",
    "name": "Rubber Duck Enterprises AS",
    "customerType": "Organization",
    "isB2B": true,
    "isPublic": false,
    "country": "NO",
    "organizationNumber": "923609016",
    "organizationData": {
      "subOrganizationName": "Rubber Duck Enterprises",
      "subOrganizationNumber": "923609016-1",
      "organizationCountry": "NO",
      "organizationIds": {}
    }
  }
}

Key points:

• No email, mobile, or primaryAddress — an organization account may not carry any of those; each is still governed by the same omit-if-absent rule as on a Person record
• organizationData fields are each independently omittable — an organization with only a subOrganizationNumber on record returns organizationData: { "subOrganizationNumber": "..." } and nothing else inside that object

---

Organization Record — organizationNumber Without organizationData

An organization can have organizationNumber on record with no further organization detail. organizationData is omitted entirely in that case — it is not returned as {} or null.

Response — 200 OK

{
  "customer": {
    "customerId": "55555555-5555-5555-5555-555555555555",
    "name": "Small Handel AS",
    "customerType": "Organization",
    "isB2B": true,
    "isPublic": false,
    "country": "NO",
    "organizationNumber": "987654321"
  }
}

---

Error Scenarios

400 — Validation Error

Returned when customerId is empty, whitespace, or not a valid GUID.

Request

GET /customers/v1/not-a-guid
Authorization: ******
Ocp-Apim-Subscription-Key: <subscription_key>

Response — 400 Bad Request

{
  "type": "<docs-base-url>/errors/validation-failed",
  "title": "Validation Failed",
  "status": 400,
  "detail": "Some fields have validation errors",
  "instance": "/customers/v1/not-a-guid",
  "code": "ERR_VALIDATION_0001",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "errors": [
    { "fieldName": "CustomerId", "message": "CustomerId must be a valid GUID." }
  ]
}

401 — Unauthorized

No response body. The request is missing or has an invalid Authorization header.

403 — Forbidden (no scope)

No response body. The token is valid but does not include the customer:read scope.

403 — Forbidden (not entitled)

Returned when the token is valid and scoped, but your account is not entitled to see this customer.

{
  "type": "<docs-base-url>/errors/access-error",
  "title": "Access Denied",
  "status": 403,
  "detail": "You do not have permission to read this customer.",
  "instance": "/customers/v1/66666666-6666-6666-6666-666666666666",
  "code": "ERR_ACCESS",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

404 — Not Found

Returned both when the customerId never existed and when it refers to a customer that has been archived or removed — the response deliberately doesn’t distinguish the two. See Customers Overview for details.

{
  "type": "<docs-base-url>/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Customer '77777777-7777-7777-7777-777777777777' either does not exist or is archived or removed.",
  "instance": "/customers/v1/77777777-7777-7777-7777-777777777777",
  "code": "ERR_NOTFOUND",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}