Organizations

In the context of the system APIs, an organization represents a third-party entity that supports the insurer's business, such as a producer.

With the Admin API, callers can create, update, and retrieve organization data through the /admin/v1/organizations endpoints. Typically, internal services associated with administrator, auditor, or underwriter roles are authorized to access the /organizations endpoints.

Querying for organizations

Authorized internal users can query for organizations. Callers can use the following endpoints to GET organization resources:

  • GET /admin/v1/organizations: Returns all organizations that are visible to the caller
  • GET /admin/v1/organizations/{organizationId}: Returns the organization with the given ID

Creating organizations

Authorized internal users can create organizations. To create an organization, callers can submit a POST request to the /admin/v1/organizations endpoint.

At minimum, the request body must contain the following fields:

  • name: Organization name
  • type.code: Organization type, from the BusinessType typelist

Optionally, the groupDescription field can be included (why?).

If the organization represents a producer, then the producerStatus.code field must also be included in the request. This field takes a value from the ProducerStatus typelist. Optionally, the tier.code field can also be included for producer organizations, and this field takes a value from the Tier typelist.

{
  "data": {
    "attributes": {
      "name": "#(args.name)",
      "producerStatus": {
        "code": "Active"
      },
      "type": {
        "code": "agency"
      }
    }
  }
}

Updating organizations

Authorized internal users can update organizations. To update an organization, callers can submit a PATCH request to the /admin/v1/organizations/{organizationId} endpoint.