Managing Child Accounts

An EMR or billing company can run the practices it serves as child accounts under its own ClaimRev account, the parent. You create each practice, set up its providers, users and API applications, and work inside it when you need to, without ClaimRev doing it for you and without your staff being added to every practice.

You can do all of this in the portal under Parent Admin, or from your own system through the child account API. Both work the same way and follow the same rules.

How it works

• Each practice is its own account. Claims, files, ERAs, users and API applications belong to the practice, and the practice's own users only see the practice.
• Your parent account manages them. Your staff open a practice from the Parent Admin list and switch into it. They are not added to the practice as users, so they do not appear on its user list.
• One level only. A child account cannot have children of its own.
• Disabling a practice takes it out of everyone's account list and stops it taking files or claims. Nothing is deleted, and you can enable it again.

Permissions

Two permissions control what your staff can do. ClaimRev links them to a role on your parent account; ask your ClaimRev contact if someone needs them.

Permission	Lets a user
parent_admin:child-accounts	See the list of child accounts and switch into one.
parent_admin:child-account-mgmt	Everything above, plus create practices and manage their details, providers, users, roles and API applications.

Someone with only the first permission sees the list and the Switch to this account button, but not Manage or Create child account.

Working in a practice

On Parent Admin, choose Switch to this account next to a practice. Everything in the portal then acts on that practice: claim search, file uploads, reports and the rest. A banner across the top reads Working in Practice (ACCT1) for your company, and its Back to button returns you to your parent account.

Creating a practice

Choose Create child account on Parent Admin and fill in:

• Company name, and optionally an Account number (exactly 5 characters; one is suggested from the name if you leave it blank).
• Your reference: your own id for the practice, for example its id in your EMR. Optional, but recommended when creating practices from your system (see Retries).
• Contact and Address.
• Roles: the roles the practice's users may be given. Only roles your account has and you hold yourself are offered.
• First user, optional: see Users.

A new practice can upload files from the start.

Managing a practice

Choose Manage next to a practice. Its page has five tabs.

Account

The company name, contact, and physical and mailing addresses. Disable or enable the practice here.

Providers

Add the practice's individual providers, and its facilities or groups, with their NPIs. Edit one to change its details, or mark it Disabled when it no longer bills there.

Choose Identifiers next to a provider to add, edit or delete its other identifiers, such as a Medicaid or Medicare provider id.

Users

Add the practice's users by email address. ClaimRev creates their sign-in if they do not have one.

• Make them the practice's administrator gives them Practice Admin for that practice, so the practice can manage its own users. You can only do this if you hold Practice Admin yourself.
• Send ClaimRev's invite email: when ticked, ClaimRev emails them an invitation to set up their sign-in. Untick it to keep everything under your own brand, then choose Set-up link next to the user and send that link yourself, from your own email or your product. The link is a password set-up key for that one person: send it only to them. ClaimRev can set your account so that the box starts unticked.
• Give a user roles from the roles on the practice that you hold yourself.

Removing a user removes them from that practice only. Their sign-in and any other accounts they belong to are unchanged.

Users from another organization. Roles belong to a person, not to an account, so you cannot add, or give roles to, someone who already belongs to a ClaimRev account outside your family of accounts, such as an outside biller who works with other companies. Contact ClaimRev for those.

Roles

The roles the practice's users may be given at all. Add one of your own account's roles that you hold, and choose whether new users get it automatically. Removing a role from the practice does not take it from users who already have it; remove it from them on the Users tab.

API applications

The applications the practice's own systems use to call the ClaimRev API, as described in Client Applications. Each application acts only as that practice.

• Name is optional. ClaimRev names it for you, and always ends the name with the practice's account number, for example Api_ACCT1.
• The key file is shown once when it is created and is never stored, so save it straight away. You can add more keys, register your own public key instead, and revoke keys.
• Give the application roles from the roles available to it on the practice that you hold yourself.
• Disable an application to stop it signing in.

There is deliberately no single application that acts for all your practices: a key that leaks exposes one practice, not all of them.

Using the API

Everything above is available to your own system through the child account API. Call it with an API application on your parent account whose role includes parent_admin:child-account-mgmt (see Authentication). That application can manage your children, but it acts as your parent account: to submit claims or pull ERAs as a practice, use an application created on that practice.

All routes are under /api/ChildAccount/v1/, on the same API server as the rest of the ClaimRev API. JSON field names are camelCase.

Practices

Method and route	What it does
GET ParentAccounts	The parent accounts you manage.
GET Children	Your child accounts.
POST Children	Creates a practice (see below).
GET Children/{account}	A practice's details.
PUT Children/{account}	Updates the company name, contact and addresses. A section left out is unchanged.
POST Children/{account}/Disable, /Enable	Disables or re-enables the practice.
GET DefaultRoleOptions	Roles a new practice may start with. Pass ?parentAccountNumber= if you manage more than one parent.
GET InviteEmailDefault	Whether ClaimRev's invite email is sent by default. Same parentAccountNumber rule.

Providers and identifiers

Method and route	What it does
GET Children/{account}/Providers	The practice's providers and facilities.
POST Children/{account}/Providers	Adds a provider (providerId 0) or updates one. Set disabled to retire it.
GET IdentifierTypes	The identifier types, for identifierTypeId.
GET Children/{account}/Providers/{providerId}/Identifiers	A provider's identifiers.
POST Children/{account}/Providers/{providerId}/Identifiers	Adds an identifier (identifierId 0) or updates one.
DELETE Children/{account}/Providers/{providerId}/Identifiers/{identifierId}	Deletes an identifier.

Users and roles

Method and route	What it does
GET Children/{account}/Users	The practice's users and their roles.
POST Children/{account}/Users	Adds a user.
DELETE Children/{account}/Users?email=	Removes a user from the practice.
POST Children/{account}/Users/SetupLink	A set-up link for one user, to send yourself.
GET Children/{account}/AssignableRoles	Roles you may give the practice's users.
POST Children/{account}/Users/Roles	Gives a user a role: { "email", "userRoleId" }.
POST Children/{account}/Users/Roles/Remove	Takes a role from a user.
GET Children/{account}/AccountRoles	The roles on the practice.
GET Children/{account}/AccountRoles/Addable	Roles you may add to the practice.
POST Children/{account}/AccountRoles	Adds a role: { "userRoleId", "autoAddToUser" }.
DELETE Children/{account}/AccountRoles/{userRoleId}	Removes a role from the practice.

API applications

Method and route	What it does
GET Children/{account}/Apps	The practice's applications.
POST Children/{account}/Apps	Creates one. The first key file, if asked for, is in the response only.
POST Children/{account}/Apps/{clientId}/Disable, /Enable	Stops or restarts its sign-in.
GET, POST Children/{account}/Apps/{clientId}/Keys	Lists keys, or adds one.
POST Children/{account}/Apps/{clientId}/PublicKeys	Registers your own public key.
POST Children/{account}/Apps/{clientId}/Keys/{keyId}/Revoke	Revokes a key.
GET Children/{account}/Apps/{clientId}/Roles	The application's roles.
GET Children/{account}/Apps/{clientId}/AssignableRoles	Roles you may give it.
POST, DELETE Children/{account}/Apps/{clientId}/Roles/{userRoleId}	Gives or takes a role.

Creating a practice

POST /api/ChildAccount/v1/Children
Content-Type: application/json

{
  "externalReferenceId": "emr-practice-1042",
  "companyName": "Sunrise Family Clinic",
  "taxId": "123456789",
  "contact": { "name": "Ada Lovelace", "phone": "5555550100", "email": "billing@sunrise.example" },
  "physicalAddress": { "address1": "1 Main St", "city": "Tulsa", "state": "OK", "zip": "74103" },
  "providers": [ { "firstName": "Ada", "lastName": "Lovelace", "npi": "1234567893" } ],
  "facilities": [ { "name": "Sunrise Family Clinic", "npi": "1245319599", "taxId": "123456789" } ],
  "users": [ { "email": "ada@sunrise.example", "firstName": "Ada", "lastName": "Lovelace", "isAdmin": true, "sendInviteEmail": false } ],
  "defaultRoles": [ { "userRoleId": 12, "autoAddToUser": true } ]
}

parentAccountNumber can be left out when you manage only one parent account. accountNumber can be left out to have one suggested. The response gives the new accountNumber and the outcome of each set-up step; check hasFailures.

Retries

Send your own externalReferenceId when creating a practice. If the same reference is sent again, for example because your call timed out and was retried, the practice created the first time is returned with created: false, and no second account is made.

Errors

Status	Meaning
403	The account is not one of your child accounts, or you lack the permission.
400	Something in the request is wrong, for example a provider or identifier that is not on that practice, or a role you do not hold. The body says what.
409	The account number you asked for is taken.

Calls that change something and answer { "succeeded", "message" } return that body with the 400 when they are refused, for example { "succeeded": false, "message": "This user belongs to another organization and cannot be added. Contact ClaimRev." }.

Single sign-on

If your users sign in to your own product through a company identity provider, see Single Sign-On with AWS Cognito for what is available today.