Customers Get Contacts

Get Contacts for Organization — `GET /customers/v1/{organizationId}/contacts`

The inverse of Get Organization for Contact: given an organization, list the people who buy under it. Uses the same sample dataset — Rubber Duck Enterprises has three contacts, Ada, Grace, and Alan.

Unlike the single-customer and organization lookups, an organization with zero contacts is not an error. 200 OK with { "contacts": [] } and 404 Not Found mean different things here — an empty array is a normal, successful answer.

Entitlement is checked once, at the organization level — not per contact.

Success Scenarios

Organization With Multiple Contacts

Request

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

Response — 200 OK

{
  "contacts": [
    {
      "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"
      }
    },
    {
      "customerId": "33333333-3333-3333-3333-333333333333",
      "name": "Grace Hopper",
      "email": "grace.hopper@example.com",
      "customerType": "Person",
      "isB2B": false,
      "isPublic": true,
      "country": ""
    },
    {
      "customerId": "44444444-4444-4444-4444-444444444444",
      "name": "Alan Turing",
      "customerType": "Person",
      "isB2B": false,
      "isPublic": true,
      "country": "GB"
    }
  ]
}

Key points:

Each entry in contacts is the same customer shape returned by GET /customers/v1/{customerId} — contacts come back as Person records, not nested under any further organization wrapper
All three of Rubber Duck Enterprises’s contacts are present — being entitled to the organization means being entitled to every contact under it, with no separate per-contact entitlement check (see the note above)

Organization With No Contacts

An organization with no contacts on record — or none visible to you — returns 200 OK with an empty array, not 404.

Request

GET /customers/v1/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa/contacts
Authorization: ******
Ocp-Apim-Subscription-Key: <subscription_key>

Response — 200 OK

{
  "contacts": []
}

Error Scenarios

400 — Validation Error

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

{
  "type": "<docs-base-url>/errors/validation-failed",
  "title": "Validation Failed",
  "status": 400,
  "detail": "Some fields have validation errors",
  "instance": "/customers/v1/not-a-guid/contacts",
  "code": "ERR_VALIDATION_0001",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "errors": [
    { "fieldName": "OrganizationId", "message": "OrganizationId 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 to the organization)

Returned when the token is valid and scoped, but your token isn’t entitled to the organization.

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