Added filter companies by tags

blog/241125-filter-companies-by-tags.md

@@ -0,0 +1,87 @@
+---
+title: "Filter companies by tags"
+date: "2024-11-25"
+tags: ["Product", "Update"]
+hide_table_of_contents: true
+authors: dcoplowe
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+The *List companies* endpoint now supports querying by tags, streamlining company management in Codat. This feature lets you retrieve groups of companies or even a specific company using your customer ID.
+
+<!--truncate-->
+
+## What's new?
+
+You can now use the [*List companies*](/platform-api#/operations/list-companies) endpoint to filter by one or more tags assigned to your companies. The tags query parameter supports the following operators with [Codat’s query language](https://docs.codat.io/using-the-api/querying):
+
+- Equals (`=`)
+- Bot equals (`!=`)
+- Contains (`~`)
+
+For example, to retrieve a specific company using your customer ID:
+
+<Tabs>
+
+<TabItem value="nodejs" label="TypeScript">
+
+```javascript
+const result = await platformClient.companies.list({
+    tags:`uid=${customerId}`,
+  });
+```
+</TabItem>
+
+<TabItem value="python" label="Python">
+
+```python
+res = platform_client.companies.list(operations.ListCompaniesRequest(
+    tags=f'uid={customerId}'
+))
+```
+</TabItem>
+
+<TabItem value="csharp" label="C#">
+
+```c#
+var res = await platformClient.Companies.ListAsync(new() {
+    Tags = $"uid={customerId}",
+});
+```
+</TabItem>
+
+<TabItem value="go" label="Go">
+
+```go
+ctx := context.Background()
+res, err := platformClient.Companies.List(ctx, operations.ListCompaniesRequest{
+    Tags: platform.String(fmt.Sprintf("uid=%d", customerId)),
+})
+```
+</TabItem>
+
+<TabItem value="java" label="Java">
+
+```java
+ListCompaniesRequest req = ListCompaniesRequest.builder()
+  .tags(String.format("uid=%d", customerId))
+  .build();
+
+ListCompaniesResponse res = platformClient.companies().list()
+  .request(req)
+  .call();
+```
+</TabItem>
+
+</Tabs>
+
+## Who is this relevant for?
+
+This feature is ideal for anyone looking to find companies based on their customer ID or to access a cohort or group of companies categorized by the products or services you provide.
+
+## How to get started?
+
+1. Begin tagging companies using the create or update company endpoints. [Learn more](/using-the-api/managing-companies#add-metadata-to-a-company).
+2. Filter companies using the *List companies* endpoint. [Learn more](/using-the-api/managing-companies#filtering-companies-by-metadata).

docs/using-the-api/managing-companies.md

@@ -371,6 +371,70 @@ If you use include a `null` or empty `tags` object in the [Update company](/plat
 
 :::
 
+#### Filtering companies by metadata 
+
+To filter companies by metadata, use the `tags` query parameter on the [List Companies](/platform-api#/operations/list-companies) endpoint.
+This allows you to retrieve companies based on tags you’ve assigned, such as finding a specific company by customer ID or retrieving a group of companies sharing the same tag.
+The tags query parameter uses the same query language as Codat's query parameter.
+[Read more](/using-the-api/querying).
+
+For example, to return a specific company by your customer ID:
+
+<Tabs>
+
+<TabItem value="nodejs" label="TypeScript">
+
+```javascript
+const result = await platformClient.companies.list({
+    tags:`uid=${customerId}`,
+  });
+```
+</TabItem>
+
+<TabItem value="python" label="Python">
+
+```python
+res = platform_client.companies.list(operations.ListCompaniesRequest(
+    tags=f'uid={customerId}'
+))
+```
+</TabItem>
+
+<TabItem value="csharp" label="C#">
+
+```c#
+var res = await platformClient.Companies.ListAsync(new() {
+    Tags = $"uid={customerId}",
+});
+```
+</TabItem>
+
+<TabItem value="go" label="Go">
+
+```go
+ctx := context.Background()
+res, err := platformClient.Companies.List(ctx, operations.ListCompaniesRequest{
+    Tags: platform.String(fmt.Sprintf("uid=%d", customerId)),
+})
+```
+</TabItem>
+
+<TabItem value="java" label="Java">
+
+```java
+ListCompaniesRequest req = ListCompaniesRequest.builder()
+  .tags(String.format("uid=%d", customerId))
+  .build();
+
+ListCompaniesResponse res = platformClient.companies().list()
+  .request(req)
+  .call();
+```
+</TabItem>
+
+</Tabs>
+
+
 ### Authorize access to company data
 
 Once you've created the company, they'll need to give you permission to read their data from a given source, like their accounting software. There are several approaches to doing this, but for simplicity we've just covered our out-of-the-box [hosted link](/auth-flow/authorize-hosted-link) approach.