0
# Company Management
1

2
Company entity management for organizations that post jobs, including company profiles, metadata, and hierarchical organization management with support for multi-company scenarios. Companies serve as the container for job postings and provide branding and organizational context.
3

4
## Capabilities
5

6
### Company Creation
7

8
Creates new company entities with comprehensive profile information including display name, external identifiers, size classification, and contact details.
9

10
```python { .api }
11
def create_company(self, parent: str, company: Company) -> Company:
12
    """
13
    Creates a new company entity.
14

15
    Parameters:
16
    - parent (str): Tenant resource name where company will be created
17
    - company (Company): Company object with required fields (display_name, external_id)
18

19
    Returns:
20
    Company: Created company with generated resource name
21

22
    Raises:
23
    - InvalidArgument: Missing required fields or invalid values
24
    - AlreadyExists: Company with same external_id already exists
25
    - PermissionDenied: Insufficient permissions to create company
26
    """
27
```
28

29
**Usage Example:**
30

31
```python
32
from google.cloud.talent import CompanyServiceClient, Company, CompanySize
33

34
client = CompanyServiceClient()
35

36
company = Company(
37
    display_name="Acme Corporation",
38
    external_id="acme-corp-001",
39
    size=CompanySize.BIG,
40
    headquarters_address="123 Business Ave, San Francisco, CA 94105",
41
    website_uri="https://www.acme.com",
42
    career_site_uri="https://careers.acme.com",
43
    image_uri="https://www.acme.com/logo.png",
44
    eeo_text="Acme Corporation is an equal opportunity employer committed to diversity and inclusion."
45
)
46

47
created_company = client.create_company(
48
    parent="projects/my-project/tenants/my-tenant",
49
    company=company
50
)
51

52
print(f"Created company: {created_company.name}")
53
```
54

55
### Company Retrieval
56

57
Retrieves individual company profiles by resource name with complete company information and metadata.
58

59
```python { .api }
60
def get_company(self, name: str) -> Company:
61
    """
62
    Retrieves a company by its resource name.
63

64
    Parameters:
65
    - name (str): Full company resource name
66

67
    Returns:
68
    Company: Complete company object with all fields
69

70
    Raises:
71
    - NotFound: Company does not exist
72
    - PermissionDenied: Insufficient permissions to view company
73
    """
74
```
75

76
**Usage Example:**
77

78
```python
79
company = client.get_company(
80
    name="projects/my-project/tenants/my-tenant/companies/company-123"
81
)
82

83
print(f"Company: {company.display_name}")
84
print(f"Size: {company.size}")
85
print(f"Website: {company.website_uri}")
86
```
87

88
### Company Updates
89

90
Updates existing company profiles with field-level control using update masks to specify which company attributes should be modified.
91

92
```python { .api }
93
def update_company(self, company: Company, update_mask: FieldMask = None) -> Company:
94
    """
95
    Updates an existing company profile.
96

97
    Parameters:
98
    - company (Company): Company object with updated values and resource name
99
    - update_mask (FieldMask): Specifies which fields to update
100

101
    Returns:
102
    Company: Updated company object
103

104
    Raises:
105
    - NotFound: Company does not exist
106
    - InvalidArgument: Invalid field values or update mask
107
    - PermissionDenied: Insufficient permissions to update company
108
    """
109
```
110

111
**Usage Example:**
112

113
```python
114
from google.protobuf import field_mask_pb2
115

116
# Update company website and careers page
117
company.website_uri = "https://www.newacme.com"
118
company.career_site_uri = "https://jobs.newacme.com"
119

120
update_mask = field_mask_pb2.FieldMask(
121
    paths=["website_uri", "career_site_uri"]
122
)
123

124
updated_company = client.update_company(
125
    company=company, 
126
    update_mask=update_mask
127
)
128
```
129

130
### Company Deletion
131

132
Removes company entities from the system. Note that companies with associated jobs cannot be deleted until all jobs are removed first.
133

134
```python { .api }
135
def delete_company(self, name: str) -> None:
136
    """
137
    Deletes a company entity.
138

139
    Parameters:
140
    - name (str): Full company resource name
141

142
    Raises:
143
    - NotFound: Company does not exist
144
    - PermissionDenied: Insufficient permissions to delete company
145
    - FailedPrecondition: Company has associated jobs that must be deleted first
146
    """
147
```
148

149
**Usage Example:**
150

151
```python
152
try:
153
    client.delete_company(
154
        name="projects/my-project/tenants/my-tenant/companies/company-123"
155
    )
156
    print("Company deleted successfully")
157
except exceptions.FailedPrecondition:
158
    print("Cannot delete company with active jobs")
159
```
160

161
### Company Listing
162

163
Lists company entities with pagination support for efficient browsing of large company datasets within a tenant.
164

165
```python { .api }
166
def list_companies(self, parent: str, page_size: int = None, 
167
                  page_token: str = None) -> ListCompaniesResponse:
168
    """
169
    Lists companies with pagination.
170

171
    Parameters:
172
    - parent (str): Tenant resource name
173
    - page_size (int): Maximum number of companies to return (max 100)
174
    - page_token (str): Token for pagination from previous response
175

176
    Returns:
177
    ListCompaniesResponse: Companies list with pagination token and metadata
178

179
    Raises:
180
    - InvalidArgument: Invalid page size
181
    - PermissionDenied: Insufficient permissions to list companies
182
    """
183
```
184

185
**Usage Example:**
186

187
```python
188
# List all companies in a tenant
189
response = client.list_companies(
190
    parent="projects/my-project/tenants/my-tenant",
191
    page_size=50
192
)
193

194
for company in response.companies:
195
    print(f"Company: {company.display_name} ({company.external_id})")
196
    print(f"  Size: {company.size}")
197
    print(f"  Website: {company.website_uri}")
198

199
# Handle pagination
200
while response.next_page_token:
201
    response = client.list_companies(
202
        parent="projects/my-project/tenants/my-tenant",
203
        page_token=response.next_page_token,
204
        page_size=50
205
    )
206
    
207
    for company in response.companies:
208
        print(f"Company: {company.display_name}")
209
```
210

211
## Company Data Model
212

213
### Company Entity
214

215
```python { .api }
216
class Company:
217
    name: str = None  # Resource name (auto-generated)
218
    display_name: str = None  # Company name (required, max 255 chars)
219
    external_id: str = None  # Client-defined company identifier (required, max 255 chars)
220
    size: CompanySize = None  # Company size category
221
    headquarters_address: str = None  # Main office address (max 1000 chars)
222
    hiring_organization: bool = None  # Whether company is actively hiring
223
    eeo_text: str = None  # Equal employment opportunity statement (max 1000 chars)
224
    website_uri: str = None  # Company website URL (max 2000 chars)
225
    career_site_uri: str = None  # Careers page URL (max 2000 chars)
226
    image_uri: str = None  # Company logo URL (max 2000 chars)
227
    keyword_searchable_job_custom_attributes: List[str] = None  # Searchable custom attributes
228
    derived_info: DerivedInfo = None  # Auto-derived company information
229
    suspended: bool = None  # Whether company is suspended
230
```
231

232
### Company Size Classification
233

234
```python { .api }
235
class CompanySize(Enum):
236
    """Company size categories based on employee count."""
237
    COMPANY_SIZE_UNSPECIFIED = 0
238
    MINI = 1  # Fewer than 50 employees
239
    SMALL = 2  # 50-99 employees
240
    SMEDIUM = 3  # 100-499 employees  
241
    MEDIUM = 4  # 500-999 employees
242
    BIG = 5  # 1,000-4,999 employees
243
    BIGGER = 6  # 5,000-9,999 employees
244
    GIANT = 7  # 10,000 or more employees
245
```
246

247
### Derived Information
248

249
```python { .api }
250
class Company.DerivedInfo:
251
    """Auto-derived company information populated by the system."""
252
    headquarters_location: Location = None  # Parsed headquarters location
253
```
254

255
## Request and Response Types
256

257
### Company Service Requests
258

259
```python { .api }
260
class CreateCompanyRequest:
261
    parent: str = None  # Tenant resource name
262
    company: Company = None  # Company to create
263

264
class GetCompanyRequest:
265
    name: str = None  # Company resource name
266

267
class UpdateCompanyRequest:
268
    company: Company = None  # Company with updates
269
    update_mask: FieldMask = None  # Fields to update
270

271
class DeleteCompanyRequest:
272
    name: str = None  # Company resource name
273

274
class ListCompaniesRequest:
275
    parent: str = None  # Tenant resource name
276
    page_size: int = None  # Page size (max 100)
277
    page_token: str = None  # Pagination token
278
```
279

280
### Company Service Responses
281

282
```python { .api }
283
class ListCompaniesResponse:
284
    companies: List[Company] = None  # List of companies
285
    next_page_token: str = None  # Pagination token for next page
286
    metadata: ResponseMetadata = None  # Response metadata
287
```
288

289
## Integration with Job Management
290

291
Companies serve as the parent entities for job postings and must be created before jobs can be posted:
292

293
```python
294
# Create company first
295
company = client.create_company(parent=tenant_name, company=company_data)
296

297
# Then create jobs under that company
298
from google.cloud.talent import JobServiceClient, Job
299

300
job_client = JobServiceClient()
301
job = Job(
302
    company=company.name,  # Reference to created company
303
    requisition_id="job-001",
304
    title="Software Engineer",
305
    description="Join our team!"
306
)
307

308
job_client.create_job(parent=tenant_name, job=job)
309
```
310

311
## Resource Path Helpers
312

313
The client provides helper methods for constructing resource paths:
314

315
```python { .api }
316
# Class methods for building resource paths
317
@classmethod
318
def company_path(cls, project: str, tenant: str, company: str) -> str:
319
    """Constructs a fully-qualified company resource name."""
320

321
@classmethod  
322
def tenant_path(cls, project: str, tenant: str) -> str:
323
    """Constructs a fully-qualified tenant resource name."""
324

325
@classmethod
326
def parse_company_path(cls, path: str) -> Dict[str, str]:
327
    """Parses a company path into its component parts."""
328
```
329

330
**Usage Example:**
331

332
```python
333
# Build resource paths
334
company_path = CompanyServiceClient.company_path(
335
    project="my-project",
336
    tenant="my-tenant", 
337
    company="company-123"
338
)
339

340
# Parse resource paths
341
path_components = CompanyServiceClient.parse_company_path(company_path)
342
print(f"Project: {path_components['project']}")
343
print(f"Tenant: {path_components['tenant']}")
344
print(f"Company: {path_components['company']}")
345
```
346

347
## Error Handling
348

349
Company management operations can raise several types of exceptions:
350

351
```python
352
from google.api_core import exceptions
353

354
try:
355
    company = client.create_company(parent=parent, company=company_data)
356
except exceptions.InvalidArgument as e:
357
    # Handle validation errors
358
    print(f"Invalid company data: {e}")
359
except exceptions.AlreadyExists as e:
360
    # Handle duplicate external_id
361
    print(f"Company already exists: {e}")
362
except exceptions.PermissionDenied as e:
363
    # Handle authorization errors
364
    print(f"Access denied: {e}")
365
```
366

367
Common error scenarios:
368
- **InvalidArgument**: Missing required fields (display_name, external_id), invalid field values, malformed URIs
369
- **AlreadyExists**: Duplicate external_id within the same tenant
370
- **NotFound**: Company or tenant does not exist
371
- **PermissionDenied**: Insufficient IAM permissions for company operations
372
- **FailedPrecondition**: Cannot delete company with associated jobs
373
- **ResourceExhausted**: API quota limits exceeded
374

375
## Best Practices
376

377
1. **External IDs**: Use consistent, meaningful external_id values that map to your internal company identifiers
378
2. **Company Profiles**: Populate company profiles completely for better job search results and candidate experience
379
3. **Logo Images**: Use high-quality company logos with proper dimensions for best display
380
4. **EEO Statements**: Include appropriate equal opportunity employment statements for legal compliance
381
5. **Website URLs**: Ensure website and career site URLs are valid and regularly maintained
382
6. **Company Hierarchy**: For large organizations, consider how to model subsidiaries and divisions using external_id naming conventions