Create and update companies

A Company resource in Cloud Talent Solution represents a single company. Any job belonging to that company refers to a job posting that is created for an open position in that company. It contains information such as the company name and address, as well as internal fields that tie the resource in the Cloud Talent Solution service back to your internal databases.

Create a company

To create a company, send a POST request to the companies endpoint, specifying at least the two required fields. Refer to the Quickstart: Create companies and jobs page for details on how to create a company. Video tutorials and interactive codelabs are also available.

The following sample shows how to create a new client to perform the request. We recommend that you create one client per program or system process, then use either connection pooling or a singleton client to share that client across multiple requests. Creating a new client with each request can cause performance problems or trigger DoS protection.

Go

To learn how to install and use the client library for CTS, see CTS client libraries. For more information, see the CTS Go API reference documentation.

To authenticate to CTS, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

import (
	"context"
	"fmt"
	"io"

	talent "cloud.google.com/go/talent/apiv4beta1"
	"cloud.google.com/go/talent/apiv4beta1/talentpb"
)

// createCompany creates a company as given.
func createCompany(w io.Writer, projectID, externalID, displayName string) (*talentpb.Company, error) {
	ctx := context.Background()

	// Initializes a companyService client.
	c, err := talent.NewCompanyClient(ctx)
	if err != nil {
		return nil, fmt.Errorf("talent.NewCompanyClient: %w", err)
	}
	defer c.Close()

	// Construct a createCompany request.
	req := &talentpb.CreateCompanyRequest{
		Parent: fmt.Sprintf("projects/%s", projectID),
		Company: &talentpb.Company{
			ExternalId:  externalID,
			DisplayName: displayName,
		},
	}

	resp, err := c.CreateCompany(ctx, req)
	if err != nil {
		return nil, fmt.Errorf("CreateCompany: %w", err)
	}

	fmt.Fprintf(w, "Created company: %q\n", resp.GetName())

	return resp, nil
}

Java

To learn how to install and use the client library for CTS, see CTS client libraries. For more information, see the CTS Java API reference documentation.

To authenticate to CTS, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

import com.google.cloud.talent.v4.Company;
import com.google.cloud.talent.v4.CompanyServiceClient;
import com.google.cloud.talent.v4.CreateCompanyRequest;
import com.google.cloud.talent.v4.TenantName;
import java.io.IOException;

public class JobSearchCreateCompany {

  public static void createCompany() throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String tenantId = "your-tenant-id";
    String displayName = "your-company-display-name";
    String externalId = "your-external-id";
    createCompany(projectId, tenantId, displayName, externalId);
  }

  // Create a company.
  public static void createCompany(
      String projectId, String tenantId, String displayName, String externalId) throws IOException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (CompanyServiceClient companyServiceClient = CompanyServiceClient.create()) {
      TenantName parent = TenantName.of(projectId, tenantId);
      Company company =
          Company.newBuilder().setDisplayName(displayName).setExternalId(externalId).build();

      CreateCompanyRequest request =
          CreateCompanyRequest.newBuilder()
              .setParent(parent.toString())
              .setCompany(company)
              .build();

      Company response = companyServiceClient.createCompany(request);
      System.out.println("Created Company");
      System.out.format("Name: %s%n", response.getName());
      System.out.format("Display Name: %s%n", response.getDisplayName());
      System.out.format("External ID: %s%n", response.getExternalId());
    }
  }
}

Node.js

To learn how to install and use the client library for CTS, see CTS client libraries. For more information, see the CTS Node.js API reference documentation.

To authenticate to CTS, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

const talent = require('@google-cloud/talent').v4;

/**
 * Create Company
 *
 * @param projectId {string} Your Google Cloud Project ID
 * @param tenantId {string} Identifier of the Tenant
 */
function sampleCreateCompany(projectId, tenantId, displayName, externalId) {
  const client = new talent.CompanyServiceClient();
  // const projectId = 'Your Google Cloud Project ID';
  // const tenantId = 'Your Tenant ID (using tenancy is optional)';
  // const displayName = 'My Company Name';
  // const externalId = 'Identifier of this company in my system';
  const formattedParent = client.tenantPath(projectId, tenantId);
  const company = {
    displayName: displayName,
    externalId: externalId,
  };
  const request = {
    parent: formattedParent,
    company: company,
  };
  client
    .createCompany(request)
    .then(responses => {
      const response = responses[0];
      console.log('Created Company');
      console.log(`Name: ${response.name}`);
      console.log(`Display Name: ${response.displayName}`);
      console.log(`External ID: ${response.externalId}`);
    })
    .catch(err => {
      console.error(err);
    });
}

Python

To learn how to install and use the client library for CTS, see CTS client libraries. For more information, see the CTS Python API reference documentation.

To authenticate to CTS, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

from google.cloud import talent


def create_company(project_id, tenant_id, display_name, external_id):
    """Create Company"""

    client = talent.CompanyServiceClient()

    # project_id = 'Your Google Cloud Project ID'
    # tenant_id = 'Your Tenant ID (using tenancy is optional)'
    # display_name = 'My Company Name'
    # external_id = 'Identifier of this company in my system'

    if isinstance(project_id, bytes):
        project_id = project_id.decode("utf-8")
    if isinstance(tenant_id, bytes):
        tenant_id = tenant_id.decode("utf-8")
    if isinstance(display_name, bytes):
        display_name = display_name.decode("utf-8")
    if isinstance(external_id, bytes):
        external_id = external_id.decode("utf-8")
    parent = f"projects/{project_id}/tenants/{tenant_id}"
    company = {"display_name": display_name, "external_id": external_id}

    response = client.create_company(parent=parent, company=company)
    print("Created Company")
    print(f"Name: {response.name}")
    print(f"Display Name: {response.display_name}")
    print(f"External ID: {response.external_id}")
    return response.name

Required fields

The following fields are required in create/update requests:

• displayName: The name of the employer displayed with the job, for example, "Google LLC".

• externalId: Your internal ID for this company. This field allows you to map your internal identifiers to the company in Google's system. If the company doesn't have a separate internal identifier, set this field to the same value as displayName.

Commonly used fields

• headquartersAddress: The street address of the company's main headquarters, which may be different from the job location. Cloud Talent Solution only accepts a single HQ location per company. The service attempts to geolocate the address, and populates a more specific location when possible in derivedInfo.headquartersLocation (which is output only).

• size: A bucket value representing the size of the company in terms of number of employees, from MINI to GIANT. See the size reference for enums and their definitions.

• eeoText: A string containing the Equal Employment Opportunity legal disclaimer text to be associated with all jobs for this company.

• keywordSearchableJobCustomAttributes: Specifies which customAttributes on this company's jobs should be indexed and searchable by general keyword search.

Confidential companies

In cases where you want to post a confidential job, we recommend creating a separate company that mimics the company's fields, but obfuscates the displayName, externalId, and any other identifying fields.

In cases where the end employer should be anonymous (for example, the Staffing Agency use case), we recommend setting the externalId and displayName to random but unique values.

Retrieve a company

Go

To learn how to install and use the client library for CTS, see CTS client libraries. For more information, see the CTS Go API reference documentation.

To authenticate to CTS, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

import (
	"context"
	"fmt"
	"io"

	talent "cloud.google.com/go/talent/apiv4beta1"
	"cloud.google.com/go/talent/apiv4beta1/talentpb"
)

// getCompany gets an existing company by its resource name.
func getCompany(w io.Writer, projectID, companyID string) (*talentpb.Company, error) {
	ctx := context.Background()

	// Initialize a companyService client.
	c, err := talent.NewCompanyClient(ctx)
	if err != nil {
		return nil, fmt.Errorf("talent.NewCompanyClient: %w", err)
	}
	defer c.Close()

	// Construct a getCompany request.
	companyName := fmt.Sprintf("projects/%s/companies/%s", projectID, companyID)
	req := &talentpb.GetCompanyRequest{
		// The resource name of the company to be retrieved.
		// The format is "projects/{project_id}/companies/{company_id}".
		Name: companyName,
	}

	resp, err := c.GetCompany(ctx, req)
	if err != nil {
		return nil, fmt.Errorf("GetCompany: %w", err)
	}

	fmt.Fprintf(w, "Company: %q\n", resp.GetName())
	fmt.Fprintf(w, "Company display name: %q\n", resp.GetDisplayName())

	return resp, nil
}

Java

To learn how to install and use the client library for CTS, see CTS client libraries. For more information, see the CTS Java API reference documentation.

To authenticate to CTS, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

import com.google.cloud.talent.v4.Company;
import com.google.cloud.talent.v4.CompanyName;
import com.google.cloud.talent.v4.CompanyServiceClient;
import com.google.cloud.talent.v4.GetCompanyRequest;
import java.io.IOException;

public class JobSearchGetCompany {

  public static void getCompany() throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String tenantId = "your-tenant-id";
    String companyId = "your-company-id";
    getCompany(projectId, tenantId, companyId);
  }

  // Get Company.
  public static void getCompany(String projectId, String tenantId, String companyId)
      throws IOException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (CompanyServiceClient companyServiceClient = CompanyServiceClient.create()) {
      CompanyName name = CompanyName.of(projectId, tenantId, companyId);

      GetCompanyRequest request = GetCompanyRequest.newBuilder().setName(name.toString()).build();

      Company response = companyServiceClient.getCompany(request);
      System.out.format("Company name: %s%n", response.getName());
      System.out.format("Display name: %s%n", response.getDisplayName());
    }
  }
}

Node.js

To learn how to install and use the client library for CTS, see CTS client libraries. For more information, see the CTS Node.js API reference documentation.

To authenticate to CTS, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

const talent = require('@google-cloud/talent').v4;

/** Get Company */
function sampleGetCompany(projectId, tenantId, companyId) {
  const client = new talent.CompanyServiceClient();
  // const projectId = 'Your Google Cloud Project ID';
  // const tenantId = 'Your Tenant ID (using tenancy is optional)';
  // const companyId = 'Company ID';
  const formattedName = client.companyPath(projectId, tenantId, companyId);
  client
    .getCompany({name: formattedName})
    .then(responses => {
      const response = responses[0];
      console.log(`Company name: ${response.name}`);
      console.log(`Display name: ${response.displayName}`);
    })
    .catch(err => {
      console.error(err);
    });
}

Python

To learn how to install and use the client library for CTS, see CTS client libraries. For more information, see the CTS Python API reference documentation.

To authenticate to CTS, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

from google.cloud import talent


def get_company(project_id, tenant_id, company_id):
    """Get Company"""

    client = talent.CompanyServiceClient()

    # project_id = 'Your Google Cloud Project ID'
    # tenant_id = 'Your Tenant ID (using tenancy is optional)'
    # company_id = 'Company ID'

    if isinstance(project_id, bytes):
        project_id = project_id.decode("utf-8")
    if isinstance(tenant_id, bytes):
        tenant_id = tenant_id.decode("utf-8")
    if isinstance(company_id, bytes):
        company_id = company_id.decode("utf-8")
    name = client.company_path(project_id, tenant_id, company_id)

    response = client.get_company(name=name)
    print(f"Company name: {response.name}")
    print(f"Display name: {response.display_name}")

List companies

Go

To learn how to install and use the client library for CTS, see CTS client libraries. For more information, see the CTS Go API reference documentation.

To authenticate to CTS, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

import (
	"context"
	"fmt"
	"io"

	talent "cloud.google.com/go/talent/apiv4beta1"
	"cloud.google.com/go/talent/apiv4beta1/talentpb"
	"google.golang.org/api/iterator"
)

// listCompanies lists all companies in the project.
func listCompanies(w io.Writer, projectID string) error {
	ctx := context.Background()

	// Initialize a compnayService client.
	c, err := talent.NewCompanyClient(ctx)
	if err != nil {
		return fmt.Errorf("talent.NewCompanyClient: %w", err)
	}
	defer c.Close()

	// Construct a listCompanies request.
	req := &talentpb.ListCompaniesRequest{
		Parent: "projects/" + projectID,
	}

	it := c.ListCompanies(ctx, req)

	for {
		resp, err := it.Next()
		if err == iterator.Done {
			return nil
		}
		if err != nil {
			return fmt.Errorf("it.Next: %w", err)
		}
		fmt.Fprintf(w, "Listing company: %q\n", resp.GetName())
		fmt.Fprintf(w, "Display name: %v\n", resp.GetDisplayName())
		fmt.Fprintf(w, "External ID: %v\n", resp.GetExternalId())
	}
}

Java

To learn how to install and use the client library for CTS, see CTS client libraries. For more information, see the CTS Java API reference documentation.

To authenticate to CTS, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

import com.google.cloud.talent.v4.Company;
import com.google.cloud.talent.v4.CompanyServiceClient;
import com.google.cloud.talent.v4.ListCompaniesRequest;
import com.google.cloud.talent.v4.TenantName;
import java.io.IOException;

public class JobSearchListCompanies {

  public static void listCompanies() throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String tenantId = "your-tenant-id";
    listCompanies(projectId, tenantId);
  }

  // List Companies.
  public static void listCompanies(String projectId, String tenantId) throws IOException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (CompanyServiceClient companyServiceClient = CompanyServiceClient.create()) {
      TenantName parent = TenantName.of(projectId, tenantId);

      ListCompaniesRequest request =
          ListCompaniesRequest.newBuilder().setParent(parent.toString()).build();

      for (Company responseItem : companyServiceClient.listCompanies(request).iterateAll()) {
        System.out.format("Company Name: %s%n", responseItem.getName());
        System.out.format("Display Name: %s%n", responseItem.getDisplayName());
        System.out.format("External ID: %s%n", responseItem.getExternalId());
      }
    }
  }
}

Node.js

To learn how to install and use the client library for CTS, see CTS client libraries. For more information, see the CTS Node.js API reference documentation.

To authenticate to CTS, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

const talent = require('@google-cloud/talent').v4;

/**
 * List Companies
 *
 * @param projectId {string} Your Google Cloud Project ID
 * @param tenantId {string} Identifier of the Tenant
 */
function sampleListCompanies(projectId, tenantId) {
  const client = new talent.CompanyServiceClient();
  // Iterate over all elements.
  // const projectId = 'Your Google Cloud Project ID';
  // const tenantId = 'Your Tenant ID (using tenancy is optional)';
  const formattedParent = client.tenantPath(projectId, tenantId);

  client
    .listCompanies({parent: formattedParent})
    .then(responses => {
      const resources = responses[0];
      for (const resource of resources) {
        console.log(`Company Name: ${resource.name}`);
        console.log(`Display Name: ${resource.displayName}`);
        console.log(`External ID: ${resource.externalId}`);
      }
    })
    .catch(err => {
      console.error(err);
    });
}

Python

To learn how to install and use the client library for CTS, see CTS client libraries. For more information, see the CTS Python API reference documentation.

To authenticate to CTS, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

from google.cloud import talent


def list_companies(project_id, tenant_id):
    """List Companies"""

    client = talent.CompanyServiceClient()

    # project_id = 'Your Google Cloud Project ID'
    # tenant_id = 'Your Tenant ID (using tenancy is optional)'

    if isinstance(project_id, bytes):
        project_id = project_id.decode("utf-8")
    if isinstance(tenant_id, bytes):
        tenant_id = tenant_id.decode("utf-8")
    parent = f"projects/{project_id}/tenants/{tenant_id}"

    # Iterate over all results
    results = []
    for company in client.list_companies(parent=parent):
        results.append(company.name)
        print(f"Company Name: {company.name}")
        print(f"Display Name: {company.display_name}")
        print(f"External ID: {company.external_id}")
    return results

Delete a company

Go

To learn how to install and use the client library for CTS, see CTS client libraries. For more information, see the CTS Go API reference documentation.

To authenticate to CTS, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

import (
	"context"
	"fmt"
	"io"

	talent "cloud.google.com/go/talent/apiv4beta1"
	"cloud.google.com/go/talent/apiv4beta1/talentpb"
)

// deleteCompany deletes an existing company. Companies with
// existing jobs cannot be deleted until those jobs have been deleted.
func deleteCompany(w io.Writer, projectID, companyID string) error {
	ctx := context.Background()

	// Initialize a companyService client.
	c, err := talent.NewCompanyClient(ctx)
	if err != nil {
		return fmt.Errorf("talent.NewCompanyClient: %w", err)
	}
	defer c.Close()

	// Construct a deleteCompany request.
	companyName := fmt.Sprintf("projects/%s/companies/%s", projectID, companyID)
	req := &talentpb.DeleteCompanyRequest{
		// The resource name of the company to be deleted.
		// The format is "projects/{project_id}/companies/{company_id}".
		Name: companyName,
	}

	if err := c.DeleteCompany(ctx, req); err != nil {
		return fmt.Errorf("DeleteCompany(%s): %w", companyName, err)
	}

	fmt.Fprintf(w, "Deleted company: %q\n", companyName)

	return nil
}

Java

To learn how to install and use the client library for CTS, see CTS client libraries. For more information, see the CTS Java API reference documentation.

To authenticate to CTS, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

import com.google.cloud.talent.v4.CompanyName;
import com.google.cloud.talent.v4.CompanyServiceClient;
import com.google.cloud.talent.v4.DeleteCompanyRequest;
import java.io.IOException;

public class JobSearchDeleteCompany {

  public static void deleteCompany() throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String tenantId = "your-tenant-id";
    String companyId = "your-company-id";
    deleteCompany(projectId, tenantId, companyId);
  }

  // Delete Company.
  public static void deleteCompany(String projectId, String tenantId, String companyId)
      throws IOException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (CompanyServiceClient companyServiceClient = CompanyServiceClient.create()) {
      CompanyName name = CompanyName.of(projectId, tenantId, companyId);

      DeleteCompanyRequest request =
          DeleteCompanyRequest.newBuilder().setName(name.toString()).build();

      companyServiceClient.deleteCompany(request);
      System.out.println("Deleted company");
    }
  }
}

Node.js

To learn how to install and use the client library for CTS, see CTS client libraries. For more information, see the CTS Node.js API reference documentation.

To authenticate to CTS, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

const talent = require('@google-cloud/talent').v4;

/** Delete Company */
function sampleDeleteCompany(projectId, tenantId, companyId) {
  const client = new talent.CompanyServiceClient();
  // const projectId = 'Your Google Cloud Project ID';
  // const tenantId = 'Your Tenant ID (using tenancy is optional)';
  // const companyId = 'ID of the company to delete';
  const formattedName = client.companyPath(projectId, tenantId, companyId);
  client.deleteCompany({name: formattedName}).catch(err => {
    console.error(err);
  });
  console.log('Deleted company');
}

Python

To learn how to install and use the client library for CTS, see CTS client libraries. For more information, see the CTS Python API reference documentation.

To authenticate to CTS, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

from google.cloud import talent


def delete_company(project_id, tenant_id, company_id):
    """Delete Company"""

    client = talent.CompanyServiceClient()

    # project_id = 'Your Google Cloud Project ID'
    # tenant_id = 'Your Tenant ID (using tenancy is optional)'
    # company_id = 'ID of the company to delete'

    if isinstance(project_id, bytes):
        project_id = project_id.decode("utf-8")
    if isinstance(tenant_id, bytes):
        tenant_id = tenant_id.decode("utf-8")
    if isinstance(company_id, bytes):
        company_id = company_id.decode("utf-8")
    name = client.company_path(project_id, tenant_id, company_id)

    client.delete_company(name=name)
    print("Deleted company")