Skip to content

Partner Management ​

Manage clients and API keys for your partner organization.

Authentication ​

All partner endpoints require a Partner token with appropriate scopes.

Required scopes:

  • client:read — For GET endpoints
  • client:write — For POST/PUT/DELETE endpoints

Client Management ​

List Clients ​

http
GET /ext/latest/partners/clients
Authorization: Bearer {token}

Query Parameters:

  • externalId (optional) — Filter by external identifier
  • limit (optional) — Page size (default: 10, max: 100)
  • offset (optional) — Page offset (default: 0)

Response:

json
{
  "data": [
    {
      "clientId": "a587f055-12ff-4009-a4b2-6300f665f35e",
      "name": "Acme Medical Group",
      "contactName": "Jane Doe",
      "contactEmail": "jdoe@acmemedical.com",
      "externalId": "acme_001",
      "groupNpi": "1234567890",
      "partnerId": "200c9e25-7f3e-4e66-85d8-6c0bde3cae7a"
    }
  ],
  "limit": 10,
  "offset": 0,
  "hasMore": false
}

Get Client ​

http
GET /ext/latest/partners/clients/{clientId}
Authorization: Bearer {token}

Response:

json
{
  "data": {
    "clientId": "a587f055-12ff-4009-a4b2-6300f665f35e",
    "name": "Acme Medical Group",
    "contactName": "Jane Doe",
    "contactEmail": "jdoe@acmemedical.com",
    "contactPhone": "555-123-4567",
    "groupNpi": "1234567890",
    "phone": "555-100-2000",
    "faxNumber": "555-100-2001",
    "externalId": "acme_001",
    "siteUrl": "https://acmemedical.com",
    "address": {
      "addressLine1": "100 Health Ave",
      "addressLine2": "Suite 200",
      "city": "Springfield",
      "state": "MA",
      "zip": "01103"
    }
  }
}

Create Client ​

http
POST /ext/latest/partners/clients
Content-Type: application/json
Authorization: Bearer {token}

Request Body:

json
{
  "name": "Acme Medical Group",
  "contactName": "Jane Doe",
  "contactEmail": "jdoe@acmemedical.com",
  "contactPhone": "555-123-4567",
  "groupNpi": "1234567890",
  "phone": "555-100-2000",
  "faxNumber": "555-100-2001",
  "externalId": "acme_001",
  "siteUrl": "https://acmemedical.com",
  "address": {
    "addressLine1": "100 Health Ave",
    "addressLine2": "Suite 200",
    "city": "Springfield",
    "state": "MA",
    "zip": "01103"
  }
}

Response (201 Created):

json
{
  "data": { ... }
}

Update Client ​

http
PUT /ext/latest/partners/clients/{clientId}
Content-Type: application/json
Authorization: Bearer {token}

Request Body: (all fields optional)

json
{
  "name": "Updated Name",
  "contactName": "John Smith",
  "contactEmail": "jsmith@acmemedical.com"
}

Response:

json
{
  "data": { ... }
}

Delete Client ​

http
DELETE /ext/latest/partners/clients/{clientId}
Authorization: Bearer {token}

Response (204 No Content): (no body)

Client Fields Reference ​

FieldTypeRequiredDescription
clientIdstring—Read-only system ID
namestringyesOrganization name (5-255 chars)
contactNamestringyesContact person name
contactEmailstringyesContact email
contactPhonestringnoContact phone
contactExternalIdstringnoExternal identifier for the contact person (nullable)
groupNpistringnoGroup NPI (10 digits)
phonestringnoOrganization phone
faxNumberstringnoOrganization fax
externalIdstringnoExternal system ID
siteUrlstringnoWebsite URL
emailAddressesstring[]noList of email addresses
addressobjectyesSee address fields below
clientOidstring—System-generated OID (read-only)
taxEinstringnoTax EIN (nullable)
partnerIdstring—Owning partner ID (read-only)
webhookUrlstringnoURL for event notifications — update only
webhookEnabledbooleannoEnable/disable webhook delivery

TIP

Webhook fields can only be set on the partner's own client record via PUT /ext/latest/client, not through this endpoint's sub-client update. See Webhooks for details.

Address Fields:

  • addressLine1 (required) — Street address
  • addressLine2 (optional) — Suite/unit
  • city (required) — City
  • state (required) — State code
  • zip (required) — ZIP code

Error Responses ​

StatusCodeDescription
400VALIDATION_ERRORMissing or invalid fields
401FORBIDDENMissing authentication or invalid token
403FORBIDDENInsufficient scopes
404RESOURCE_NOT_FOUNDResource not found
409RESOURCE_EXISTSDuplicate name or external ID

Vivlio Health API Documentation