talent-software.readme.io/reference/post_api-v1-group-companies

This guide explains how to restrict system templates to specific companies by using Groups, Group Templates, and Group Companies.

By creating a group and associating:

• Templates → via Group Templates
• Companies → via Group Companies

You control which companies can access specific system templates.

Currently, the Groups API is available only for Private Lable Admins.

Overview

A Group acts as a container that connects:

• Group Templates
  A polymorphic association to a:

  • Task Template
  • Step Template
  • Workflow Template

  These are the system templates that should be made visible to companies in this group.

• Group Companies
  An association to companies that should be able to see and use the group's available templates.

High-Level Flow

1. Create a Group
2. Use the returned id to:
   • Create Group Templates
   • Create Group Companies
3. Templates become visible only to the companies associated with that group.

All groups and their associations can be:

• Created
• Listed
• Deleted

Quickest Approach

1. Go to talent-software.readme.io/reference/post_api-v1-groups
2. Add your API credentials in the top right corner - username maps to key and password to secret
3. Give your group a detailed name, and optional description, and the private label id
4. Click "Try It" to fire off the request and note the id from the payload
5. Go to talent-software.readme.io/reference/post_api-v1-group-companies
6. Enter company_id for the company that is apart of this group and group_id comes from the result of step 4
7. Go to talent-software.readme.io/reference/post_api-v1-group-templates
8. Find the template's id we want to apply to this group and enter it's templatable_id as the template's id and templatable_type as either "WorkflowTemplate", "StepTemplate", or "TaskTemplate"
9. Repeat steps 5 and 7 if there are more than 1 company or 1 template in the group

**Note it is not necessary to add a task group or workflow's children unless we want them to explicitly show up as individual tasks. For example in an I-9 group, all we have to do is create a group template with the task group only.

If this is for I-9/E-Verify, reach out to an engineer to confirm that the task group exists for the private label

A more detailed approach is down below -

Step 1 — Create a Group

Create a group using:

POST /api/v1/groups

Documentation:

talent-software.readme.io/reference/post_api-v1-groups

Example Request

curl -X POST https://api.yourdomain.com/api/v1/groups \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Restricted System Templates - Enterprise Clients",
    "description": "Group restricting system templates to specific enterprise companies"
		"private_label_id": "1"
  }'

Example Response

{
  "id": 42,
  "name": "Restricted System Templates - Enterprise Clients",
  "description": "Group restricting system templates to specific enterprise companies",
	"private_label_id": "1",
  "created_at": "2026-02-20T12:00:00Z",
  "updated_at": "2026-02-20T12:00:00Z"
}

You must store the returned id (e.g., 42). This group_id will be used to create:

• Group Templates
• Group Companies

Step 2 — Associate Templates to the Group

Create Group Templates using:

POST /api/v1/group_templates

Documentation:

talent-software.readme.io/reference/post_api-v1-group-templates

What is a Group Template?

A Group Template is a polymorphic association to one of the following:

• TaskTemplate
• StepTemplate
• WorkflowTemplate

This determines which system templates are visible to companies within this group.

Example Request

curl -X POST https://api.yourdomain.com/api/v1/group_templates \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": 42,
    "templatable_id": 1001,
    "templatable_type": "WorkflowTemplate"
  }'

Example Payload Fields

You may repeat this call to associate multiple templates to the same group.

Step 3 — Associate Companies to the Group

Create Group Companies using:

POST /api/v1/group_companies

Documentation:

talent-software.readme.io/reference/post_api-v1-group-companies

A Group Company associates a company to a group.

Companies added here will gain visibility to all templates associated with the group.

Example Request

curl -X POST https://api.yourdomain.com/api/v1/group_companies \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": 42,
    "company_id": 555
  }'

Example Payload Fields

Repeat this call to associate multiple companies to the same group.

Resulting Behavior

Once configured:

• Only companies linked via Group Companies
• Can access templates linked via Group Templates
• Within that specific group

Listing Resources

You can list all created resources.

List Groups

GET /api/v1/groups

List Group Templates

GET /api/v1/group_templates
GET /api/v1/groups/:group_id/group_templates

List Group Companies

GET /api/v1/group_companies
GET /api/v1/groups/:group_id/group_companies

Deleting Resources

All entities can be deleted if needed.

Delete Group

DELETE /api/v1/groups/{group_id}

Delete Group Template

DELETE /api/v1/group_templates/{group_template_id}

Delete Group Company

DELETE /api/v1/group_companies/{group_company_id}

Deleting a group does not automatically imply deletion of system templates or companies — only the association is removed.

For full endpoint details and request/response schemas, refer to:

• talent-software.readme.io/reference/get_api-v1-groups
• talent-software.readme.io/reference/get_api-v1-group_companies
• talent-software.readme.io/reference/get_api-v1-group_templates