> ## Documentation Index
> Fetch the complete documentation index at: https://dub.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Organizing links

> Learn how to associate links with users, campaigns, teams, and other entities within your system.

When creating links programmatically with Dub, you might want a way to associate them with a user or other identifiers in your system.

There are a few ways to do this, depending on your data structure:

| Method                      | Type         | Description                                        | Use case                                                                                              |
| --------------------------- | ------------ | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| [External ID](#external-id) | One-to-one   | A unique identifier for a link within your system. | Associating referral links with users in your system.                                                 |
| [Tenant ID](#tenant-id)     | One-to-many  | The ID of the tenant that created the link.        | Grouping all links created by a user/team in your system.                                             |
| [Tags](#tags)               | Many-to-many | Grouping links by tags                             | Organizing links by campaign / user / various for flexible, multi-dimensional filtering and reporting |
| [Folders](#folders)         | One-to-many  | The ID of the folder that contains the link.       | Organizing links into hierarchical folder structures for better organization.                         |

## External ID

In certain scenarios, it is essential to identify links within your system. For instance, you may need to associate a link with a user without storing the Dub link ID directly in your database (e.g. for referral links).

The `externalId` field serves this purpose effectively. It acts as a unique identifier within your database, allowing you to associate it with a corresponding link in Dub's system.

Dub allows you to create links using an `externalId` and subsequently retrieve them by the same identifier.

<Note>
  `externalId` should be a unique value across your workspace. Trying to create
  a link with an externalId that already exists will result in a [`409` conflict
  error](/docs/api-reference/introduction#conflict) error.
</Note>

### Create link with an externalId

Here is an example of how to create a link with an `externalId`:

<CodeGroup>
  ```javascript Node.js theme={null}
  import { Dub } from "dub";

  export const dub = new Dub({
    token: process.env.DUB_API_KEY,
  });

  const link = await dub.links.create({
    url: "https://google.com",
    externalId: "12345",
  });
  ```

  ```go Go theme={null}
  package main

  import(
    "context"
    dubgo "github.com/dubinc/dub-go"
    "github.com/dubinc/dub-go/models/operations"
    "log"
    "os"
  )

  func main() {
    ctx := context.Background()

    s := dubgo.New(
      dubgo.WithSecurity(os.Getenv("DUB_API_KEY")),
    )

    res, err := s.Links.Create(ctx, &operations.CreateLinkRequestBody{
      URL: "https://google.com",
      ExternalId: "12345",
    })

    if err != nil {
      log.Fatal(err)
    }

    if res != nil {
      // handle response
    }
  }
  ```

  ```python Python theme={null}
  import os
  import dub
  from dub.models import operations

  d = dub.Dub(
    token=os.environ['DUB_API_KEY'],
  )

  res = d.links.create(request={
    "url": "https://google.com",
    "external_id": "12345",
  })
  ```

  ```ruby Ruby theme={null}
  require 'dub'

  s = ::OpenApiSDK::Dub.new
  s.config_security(
    ::OpenApiSDK::Shared::Security.new(
      token: "DUB_API_KEY",
    )
  )

  req = ::OpenApiSDK::Operations::CreateLinkRequestBody.new(
    url: "https://google.com",
    external_id: "12345",
  )
  ```

  ```php PHP theme={null}
  declare(strict_types=1);

  require 'vendor/autoload.php';

  use Dub;
  use Dub\Models\Operations;

  $sdk = Dub\Dub::builder()->setSecurity('DUB_API_KEY')->build();

  $request = new Operations\CreateLinkRequestBody(
    url: 'https://google.com',
    externalId: '12345',
  );

  $response = $sdk->links->create(
    request: $request
  );
  ```

  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.dub.co/links \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "url": "https://google.com",
      "external_id": "12345"
    }'
  ```
</CodeGroup>

### Retrieve link by externalId

Let's see how to retrieve a link by its `externalId`:

<CodeGroup>
  ```javascript Node.js theme={null}
  import { Dub } from "dub";

  export const dub = new Dub({
    token: process.env.DUB_API_KEY,
  });

  const link = await dub.links.get({
    externalId: "12345",
  });
  ```

  ```go Go theme={null}
  package main

  import(
    "context"
    dubgo "github.com/dubinc/dub-go"
    "github.com/dubinc/dub-go/models/operations"
    "log"
    "os"
  )

  func main() {
    ctx := context.Background()

    s := dubgo.New(
      dubgo.WithSecurity(os.Getenv("DUB_API_KEY")),
    )

    res, err := s.Links.Get(ctx, operations.GetLinkInfoRequest{
      ExternalID: dubgo.String("12345"),
    })
  }
  ```

  ```python Python theme={null}
  import os
  import dub
  from dub.models import operations

  d = dub.Dub(
    token=os.environ['DUB_API_KEY'],
  )

  res = d.links.get(request={
    "external_id": "12345",
  })
  ```

  ```ruby Ruby theme={null}
  require 'dub'

  s = ::OpenApiSDK::Dub.new
  s.config_security(
    ::OpenApiSDK::Shared::Security.new(
      token: "DUB_API_KEY",
    )
  )

  req = ::OpenApiSDK::Operations::GetLinkInfoRequest.new(
    external_id: "12345",
  )

  res = s.links.get(req)
  ```

  ```php PHP theme={null}
  declare(strict_types=1);

  require 'vendor/autoload.php';

  use Dub;
  use Dub\Models\Operations;

  $sdk = Dub\Dub::builder()->setSecurity('DUB_API_KEY')->build();

  $response = $sdk->links->get(
    externalId: '12345'
  );
  ```

  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.dub.co/links/info?external_id=12345 \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json'
  ```
</CodeGroup>

### Update link by externalId

In addition to updating a link by its `linkId`, you can also update a link by its `externalId`.

<Note>
  Make sure to prefix the `externalId` with `ext_`. For example, if your
  `externalId` is `12345`, you should pass `ext_12345`.
</Note>

<CodeGroup>
  ```javascript Node.js theme={null}
  import { Dub } from "dub";

  export const dub = new Dub({
    token: process.env.DUB_API_KEY,
  });

  const link = await dub.links.update("ext_12345", {
    url: "https://www.google.uk", // new URL
  });
  ```

  ```go Go theme={null}
  package main

  import(
    "context"
    dubgo "github.com/dubinc/dub-go"
    "github.com/dubinc/dub-go/models/operations"
    "log"
    "os"
  )

  func main() {
    ctx := context.Background()

    s := dubgo.New(
      dubgo.WithSecurity(os.Getenv("DUB_API_KEY")),
    )

    res, err := s.Links.Update(ctx, "ext_12345", &operations.UpdateLinkRequestBody{
      URL: "https://www.google.uk", // new URL
    })

    if err != nil {
      log.Fatal(err)
    }

    if res != nil {
      // handle response
    }
  }
  ```

  ```python Python theme={null}
  import os
  import dub
  from dub.models import operations

  d = dub.Dub(
    token=os.environ['DUB_API_KEY'],
  )

  res = dub.links.update(link_id="ext_12345", request_body={
    "url": "https://www.google.uk", // new URL
  })
  ```

  ```ruby Ruby theme={null}
  require 'dub'

  s = ::OpenApiSDK::Dub.new
  s.config_security(
    ::OpenApiSDK::Shared::Security.new(
      token: "DUB_API_KEY",
    )
  )

  res = s.links.update(link_id="ext_12345", request_body={
    "url": "https://www.google.uk", // new URL
  })
  ```

  ```php PHP theme={null}
  declare(strict_types=1);

  require 'vendor/autoload.php';

  use Dub;
  use Dub\Models\Operations;

  $sdk = Dub\Dub::builder()->setSecurity('DUB_API_KEY')->build();

  $requestBody = new Operations\UpdateLinkRequestBody(
    url: 'https://www.google.uk', // new URL
  );

  $response = $sdk->links->update(
    linkId: 'ext_12345',
    requestBody: $requestBody
  );
  ```

  ```bash cURL theme={null}
  curl --request PATCH \
    --url https://api.dub.co/links/ext_12345 \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{"url": "https://www.google.uk"}'
  ```
</CodeGroup>

### Retrieve analytics by externalId

You can also retrieve analytics for a link by its `externalId`. This is helpful for fetching the analytics for a given link using the unique identifier from your system.

<CodeGroup>
  ```javascript Node.js theme={null}
  import { Dub } from "dub";

  export const dub = new Dub({
    token: process.env.DUB_API_KEY,
  });

  const analytics = await dub.analytics.retrieve({
    externalId: "ext_12345",
  });
  ```

  ```go Go theme={null}
  package main

  import(
    "context"
    dubgo "github.com/dubinc/dub-go"
    "github.com/dubinc/dub-go/models/operations"
    "log"
    "os"
  )

  func main() {
    ctx := context.Background()

    s := dubgo.New(
      dubgo.WithSecurity(os.Getenv("DUB_API_KEY")),
    )

    res, err := s.Analytics.Retrieve(ctx, operations.RetrieveAnalyticsRequest{
      ExternalID: dubgo.String("ext_12345"),
    })
  }
  ```

  ```python Python theme={null}
  import os
  import dub
  from dub.models import operations

  d = dub.Dub(
    token=os.environ['DUB_API_KEY'],
  )

  res = dub.analytics.retrieve(request={
    "external_id": "ext_12345",
  })
  ```

  ```ruby Ruby theme={null}
  require 'dub'

  s = ::OpenApiSDK::Dub.new
  s.config_security(
    ::OpenApiSDK::Shared::Security.new(
      token: "DUB_API_KEY",
    )
  )

  req = ::OpenApiSDK::Operations::RetrieveAnalyticsRequest.new(
    external_id: "ext_12345",
  )

  res = s.analytics.retrieve(req)
  ```

  ```php PHP theme={null}
  declare(strict_types=1);

  require 'vendor/autoload.php';

  use Dub;
  use Dub\Models\Operations;

  $sdk = Dub\Dub::builder()->setSecurity('DUB_API_KEY')->build();

  $request = new Operations\RetrieveAnalyticsRequest(
    externalId: "ext_12345",
  );

  $response = $sdk->analytics->retrieve(
    request: $request
  );
  ```

  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.dub.co/analytics?external_id=ext_12345 \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json'
  ```
</CodeGroup>

## Tenant ID

The ID of the tenant that created the link inside your system. If set, it can be used to fetch all links for a tenant. This is useful if you have a system that lets your users create their own links, and you want to group them on a tenant level.

### Create link with tenantId

Let's see how to create a link with a tenant ID:

<CodeGroup>
  ```javascript Node.js theme={null}
  import { Dub } from "dub";

  export const dub = new Dub({
    token: process.env.DUB_API_KEY,
  });

  const link = await dub.links.create({
    url: "https://google.com",
    tenantId: "12345",
  });
  ```

  ```go Go theme={null}
  package main

  import(
    "context"
    dubgo "github.com/dubinc/dub-go"
    "github.com/dubinc/dub-go/models/operations"
    "log"
    "os"
  )

  func main() {
    ctx := context.Background()

    s := dubgo.New(
      dubgo.WithSecurity(os.Getenv("DUB_API_KEY")),
    )

    res, err := s.Links.Create(ctx, &operations.CreateLinkRequestBody{
      URL: "https://google.com",
      TenantId: "12345",
    })

    if err != nil {
      log.Fatal(err)
    }

    if res != nil {
      // handle response
    }
  }
  ```

  ```python Python theme={null}
  import os
  import dub
  from dub.models import operations

  d = dub.Dub(
    token=os.environ['DUB_API_KEY'],
  )

  res = d.links.create(request={
    "url": "https://google.com",
    "tenant_id": "12345",
  })
  ```

  ```ruby Ruby theme={null}
  require 'dub'

  s = ::OpenApiSDK::Dub.new
  s.config_security(
    ::OpenApiSDK::Shared::Security.new(
      token: "DUB_API_KEY",
    )
  )

  req = ::OpenApiSDK::Operations::CreateLinkRequestBody.new(
    url: "https://google.com",
    tenant_id: "12345",
  )
  ```

  ```php PHP theme={null}
  declare(strict_types=1);

  require 'vendor/autoload.php';

  use Dub;
  use Dub\Models\Operations;

  $sdk = Dub\Dub::builder()->setSecurity('DUB_API_KEY')->build();

  $request = new Operations\CreateLinkRequestBody(
    url: 'https://google.com',
    tenantId: '12345',
  );

  $response = $sdk->links->create(
    request: $request
  );
  ```

  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.dub.co/links \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "url": "https://google.com",
      "external_id": "12345"
    }'
  ```
</CodeGroup>

### Retrieve links by tenantId

Here is how to retrieve links by tenant ID:

<CodeGroup>
  ```javascript Node.js theme={null}
  import { Dub } from "dub";

  export const dub = new Dub({
    token: process.env.DUB_API_KEY,
  });

  const result = await dub.links.list({
    tenantId: "12345",
  });
  ```

  ```go Go theme={null}
  package main

  import(
    "context"
    dubgo "github.com/dubinc/dub-go"
    "github.com/dubinc/dub-go/models/operations"
    "log"
    "os"
  )

  func main() {
    ctx := context.Background()

    s := dubgo.New(
      dubgo.WithSecurity(os.Getenv("DUB_API_KEY")),
    )

    res, err := s.Links.List(ctx, operations.GetLinksRequest{
      TenantId: dubgo.String("12345"),
    })
  }
  ```

  ```python Python theme={null}
  import os
  import dub
  from dub.models import operations

  d = dub.Dub(
    token=os.environ['DUB_API_KEY'],
  )

  res = s.links.list(request={
    "tenant_id": "12345",
  })
  ```

  ```ruby Ruby theme={null}
  require 'dub'

  s = ::OpenApiSDK::Dub.new
  s.config_security(
    ::OpenApiSDK::Shared::Security.new(
      token: "DUB_API_KEY",
    )
  )

  req = ::OpenApiSDK::Operations::GetLinksRequest.new(
    tenant_id: "12345",
  )

  res = s.links.list(req)
  ```

  ```php PHP theme={null}
  declare(strict_types=1);

  require 'vendor/autoload.php';

  use Dub;
  use Dub\Models\Operations;

  $sdk = Dub\Dub::builder()->setSecurity('DUB_API_KEY')->build();

  $request = new Operations\GetLinksRequest(
    tenantId: "12345",
  );

  $responses = $sdk->links->list(
    request: $request
  );

  ```

  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.dub.co/links?tenantId=12345 \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json'
  ```
</CodeGroup>

### Retrieve analytics by tenantId

You can retrieve analytics by tenantId by passing the `tenantId` prop. This is helpful for fetching the analytics for all the links under a specific tenant, or the total analytics for a tenant.

<CodeGroup>
  ```javascript Node.js theme={null}
  import { Dub } from "dub";

  export const dub = new Dub({
    token: process.env.DUB_API_KEY,
  });

  const analytics = await dub.analytics.retrieve({
    tenantId: "12345",
  });
  ```

  ```go Go theme={null}
  package main

  import(
    "context"
    dubgo "github.com/dubinc/dub-go"
    "github.com/dubinc/dub-go/models/operations"
    "log"
    "os"
  )

  func main() {
    ctx := context.Background()

    s := dubgo.New(
      dubgo.WithSecurity(os.Getenv("DUB_API_KEY")),
    )

    res, err := s.Analytics.Retrieve(ctx, operations.RetrieveAnalyticsRequest{
      TenantId: dubgo.String("12345"),
    })
  }
  ```

  ```python Python theme={null}
  import os
  import dub
  from dub.models import operations

  d = dub.Dub(
    token=os.environ['DUB_API_KEY'],
  )

  res = dub.analytics.retrieve(request={
    "tenant_id": "12345",
  })
  ```

  ```ruby Ruby theme={null}
  require 'dub'

  s = ::OpenApiSDK::Dub.new
  s.config_security(
    ::OpenApiSDK::Shared::Security.new(
      token: "DUB_API_KEY",
    )
  )

  req = ::OpenApiSDK::Operations::RetrieveAnalyticsRequest.new(
    tenant_id: "12345",
  )

  res = s.analytics.retrieve(req)
  ```

  ```php PHP theme={null}
  declare(strict_types=1);

  require 'vendor/autoload.php';

  use Dub;
  use Dub\Models\Operations;

  $sdk = Dub\Dub::builder()->setSecurity('DUB_API_KEY')->build();

  $request = new Operations\RetrieveAnalyticsRequest(
    tenantId: "12345",
  );

  $response = $sdk->analytics->retrieve(
    request: $request
  );
  ```

  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.dub.co/analytics?tenantId=12345 \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json'
  ```
</CodeGroup>

***

## Tags

Tags are a great way to organize your links on Dub.

With tags, you can:

* Organize your links by campaigns, clients, or any other categories you can think of.
* [Filter your links by tags](#retrieve-links-by-tags) and get a shareable link to the filtered results.
* [Filter your analytics by tags](#retrieve-analytics-by-tags) to see how your campaigns are performing.

### Create link with tags

You can use either pass the tag ID or tag name to create a link with tags.

<CodeGroup>
  ```javascript Node.js theme={null}
  import { Dub } from "dub";

  export const dub = new Dub({
    token: process.env.DUB_API_KEY,
  });

  const link = await dub.links.create({
    url: "https://example.com",
    tagIds: ["clux0rgak00011..."],
  });
  ```

  ```go Go theme={null}
  package main

  import(
    "context"
    dubgo "github.com/dubinc/dub-go"
    "github.com/dubinc/dub-go/models/operations"
    "log"
    "os"
  )

  func main() {
    ctx := context.Background()

    s := dubgo.New(
      dubgo.WithSecurity(os.Getenv("DUB_API_KEY")),
    )

    res, err := s.Links.Create(ctx, &operations.CreateLinkRequestBody{
      URL: "https://example.com",
      TagIds: []string{"clux0rgak00011..."},
    })

    if err != nil {
      log.Fatal(err)
    }

    if res != nil {
      // handle response
    }
  }
  ```

  ```python Python theme={null}
  import os
  import dub
  from dub.models import operations

  d = dub.Dub(
    token=os.environ['DUB_API_KEY'],
  )

  res = d.links.create(request={
    "url": "https://example.com",
    "tag_ids": ["clux0rgak00011..."],
  })
  ```

  ```ruby Ruby theme={null}
  require 'dub'

  s = ::OpenApiSDK::Dub.new
  s.config_security(
    ::OpenApiSDK::Shared::Security.new(
      token: "DUB_API_KEY",
    )
  )

  req = ::OpenApiSDK::Operations::CreateLinkRequestBody.new(
    url: "https://example.com",
    tag_ids: ["clux0rgak00011..."],
  )
  ```

  ```php PHP theme={null}
  declare(strict_types=1);

  require 'vendor/autoload.php';

  use Dub;
  use Dub\Models\Operations;

  $sdk = Dub\Dub::builder()->setSecurity('DUB_API_KEY')->build();

  $request = new Operations\CreateLinkRequestBody(
    url: 'https://example.com',
    tagIds: ['clux0rgak00011...'],
  );

  $response = $sdk->links->create(
    request: $request
  );
  ```

  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.dub.co/links \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "url": "https://example.com",
      "tagIds": ["clux0rgak00011..."]
    }'
  ```
</CodeGroup>

### Retrieve links by tags

You can retrieve links by tag by tags.

<CodeGroup>
  ```javascript Node.js theme={null}
  import { Dub } from "dub";

  export const dub = new Dub({
    token: process.env.DUB_API_KEY,
  });

  const result = await dub.links.list({
    tagNames: ["tag1"],
  });
  ```

  ```go Go theme={null}
  package main

  import(
    "context"
    dubgo "github.com/dubinc/dub-go"
    "github.com/dubinc/dub-go/models/operations"
    "log"
    "os"
  )

  func main() {
    ctx := context.Background()

    s := dubgo.New(
      dubgo.WithSecurity(os.Getenv("DUB_API_KEY")),
    )

    res, err := s.Links.List(ctx, operations.GetLinksRequest{
      TagNames: []string{"tag1"},
    })
  }
  ```

  ```python Python theme={null}
  import os
  import dub
  from dub.models import operations

  d = dub.Dub(
    token=os.environ['DUB_API_KEY'],
  )

  res = s.links.list(request={
    "tag_names": ["tag1"],
  })
  ```

  ```ruby Ruby theme={null}
  require 'dub'

  s = ::OpenApiSDK::Dub.new
  s.config_security(
    ::OpenApiSDK::Shared::Security.new(
      token: "DUB_API_KEY",
    )
  )

  req = ::OpenApiSDK::Operations::GetLinksRequest.new(
    tag_names: ["tag1"],
  )

  res = s.links.list(req)
  ```

  ```php PHP theme={null}
  declare(strict_types=1);

  require 'vendor/autoload.php';

  use Dub;
  use Dub\Models\Operations;

  $sdk = Dub\Dub::builder()->setSecurity('DUB_API_KEY')->build();

  $request = new Operations\GetLinksRequest(
    tagNames: ["tag1"],
  );

  $responses = $sdk->links->list(
    request: $request
  );

  ```

  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.dub.co/links?tagNames=tag1 \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json'
  ```
</CodeGroup>

### Retrieve analytics by tags

You can retrieve analytics for a tag (or multiple tags) by passing the `tagIds` prop. This is helpful for fetching the analytics for all the links under a specific tag, or the total analytics for a tag (or multiple tags).

<CodeGroup>
  ```javascript Node.js theme={null}
  import { Dub } from "dub";

  export const dub = new Dub({
    token: process.env.DUB_API_KEY,
  });

  const analytics = await dub.analytics.retrieve({
    tagIds: ["tag_xxx"],
  });
  ```

  ```go Go theme={null}
  package main

  import(
    "context"
    dubgo "github.com/dubinc/dub-go"
    "github.com/dubinc/dub-go/models/operations"
    "log"
    "os"
  )

  func main() {
    ctx := context.Background()

    s := dubgo.New(
      dubgo.WithSecurity(os.Getenv("DUB_API_KEY")),
    )

    res, err := s.Analytics.Retrieve(ctx, operations.RetrieveAnalyticsRequest{
      TagIds: []string{"tag_xxx"},
    })
  }
  ```

  ```python Python theme={null}
  import os
  import dub
  from dub.models import operations

  d = dub.Dub(
    token=os.environ['DUB_API_KEY'],
  )

  res = dub.analytics.retrieve(request={
    "tag_ids": ["tag_xxx"],
  })
  ```

  ```ruby Ruby theme={null}
  require 'dub'

  s = ::OpenApiSDK::Dub.new
  s.config_security(
    ::OpenApiSDK::Shared::Security.new(
      token: "DUB_API_KEY",
    )
  )

  req = ::OpenApiSDK::Operations::RetrieveAnalyticsRequest.new(
    tag_ids: ["tag_xxx"],
  )

  res = s.analytics.retrieve(req)
  ```

  ```php PHP theme={null}
  declare(strict_types=1);

  require 'vendor/autoload.php';

  use Dub;
  use Dub\Models\Operations;

  $sdk = Dub\Dub::builder()->setSecurity('DUB_API_KEY')->build();

  $request = new Operations\RetrieveAnalyticsRequest(
    tagIds: ["tag_xxx"],
  );

  $response = $sdk->analytics->retrieve(
    request: $request
  );
  ```

  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.dub.co/analytics?tagIds=tag_xxx \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json'
  ```
</CodeGroup>

***

## Folders

Folders are a hierarchical way to organize your links on Dub.

With folders, you can:

* Organize your links into directories
* [Filter your links by folder](#retrieve-links-by-folders) and get a shareable link to the filtered results.
* [Filter your analytics by folder](#retrieve-analytics-by-folders) to see how your campaigns are performing.

### Create link with folderId

You can use the folder ID to create a link with a folder.

<CodeGroup>
  ```javascript Node.js theme={null}
  import { Dub } from "dub";

  export const dub = new Dub({
    token: process.env.DUB_API_KEY,
  });

  const link = await dub.links.create({
    url: "https://example.com",
    folderId: "clux0rgak00011...",
  });
  ```

  ```go Go theme={null}
  package main

  import(
    "context"
    dubgo "github.com/dubinc/dub-go"
    "github.com/dubinc/dub-go/models/operations"
    "log"
    "os"
  )

  func main() {
    ctx := context.Background()

    s := dubgo.New(
      dubgo.WithSecurity(os.Getenv("DUB_API_KEY")),
    )

    res, err := s.Links.Create(ctx, &operations.CreateLinkRequestBody{
      URL: "https://example.com",
      FolderId: "clux0rgak00011...",
    })

    if err != nil {
      log.Fatal(err)
    }

    if res != nil {
      // handle response
    }
  }
  ```

  ```python Python theme={null}
  import os
  import dub
  from dub.models import operations

  d = dub.Dub(
    token=os.environ['DUB_API_KEY'],
  )

  res = d.links.create(request={
    "url": "https://example.com",
    "folder_id": "clux0rgak00011...",
  })
  ```

  ```ruby Ruby theme={null}
  require 'dub'

  s = ::OpenApiSDK::Dub.new
  s.config_security(
    ::OpenApiSDK::Shared::Security.new(
      token: "DUB_API_KEY",
    )
  )

  req = ::OpenApiSDK::Operations::CreateLinkRequestBody.new(
    url: "https://example.com",
    folder_id: "clux0rgak00011...",
  )
  ```

  ```php PHP theme={null}
  declare(strict_types=1);

  require 'vendor/autoload.php';

  use Dub;
  use Dub\Models\Operations;

  $sdk = Dub\Dub::builder()->setSecurity('DUB_API_KEY')->build();

  $request = new Operations\CreateLinkRequestBody(
    url: 'https://example.com',
    folderId: 'clux0rgak00011...',
  );

  $response = $sdk->links->create(
    request: $request
  );
  ```

  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.dub.co/links \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "url": "https://example.com",
      "folderId": "clux0rgak00011..."
    }'
  ```
</CodeGroup>

### Retrieve links by folderId

Here is how to retrieve links by folder ID:

<CodeGroup>
  ```javascript Node.js theme={null}
  import { Dub } from "dub";

  export const dub = new Dub({
    token: process.env.DUB_API_KEY,
  });

  const result = await dub.links.list({
    folderId: "clux0rgak00011...",
  });
  ```

  ```go Go theme={null}
  package main

  import(
    "context"
    dubgo "github.com/dubinc/dub-go"
    "github.com/dubinc/dub-go/models/operations"
    "log"
    "os"
  )

  func main() {
    ctx := context.Background()

    s := dubgo.New(
      dubgo.WithSecurity(os.Getenv("DUB_API_KEY")),
    )

    res, err := s.Links.List(ctx, operations.GetLinksRequest{
      FolderId: dubgo.String("clux0rgak00011..."),
    })
  }
  ```

  ```python Python theme={null}
  import os
  import dub
  from dub.models import operations

  d = dub.Dub(
    token=os.environ['DUB_API_KEY'],
  )

  res = s.links.list(request={
    "folder_id": "clux0rgak00011...",
  })
  ```

  ```ruby Ruby theme={null}
  require 'dub'

  s = ::OpenApiSDK::Dub.new
  s.config_security(
    ::OpenApiSDK::Shared::Security.new(
      token: "DUB_API_KEY",
    )
  )

  req = ::OpenApiSDK::Operations::GetLinksRequest.new(
    folder_id: "clux0rgak00011...",
  )

  res = s.links.list(req)
  ```

  ```php PHP theme={null}
  declare(strict_types=1);

  require 'vendor/autoload.php';

  use Dub;
  use Dub\Models\Operations;

  $sdk = Dub\Dub::builder()->setSecurity('DUB_API_KEY')->build();

  $request = new Operations\GetLinksRequest(
    folderId: "clux0rgak00011...",
  );

  $responses = $sdk->links->list(
    request: $request
  );

  ```

  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.dub.co/links?folderId=clux0rgak00011... \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json'
  ```
</CodeGroup>

### Retrieve analytics by folderId

You can retrieve analytics by folderId by passing the `folderId` prop. This is helpful for fetching the analytics for all the links under a specific folder, or the total analytics for a folder.

<CodeGroup>
  ```javascript Node.js theme={null}
  import { Dub } from "dub";

  export const dub = new Dub({
    token: process.env.DUB_API_KEY,
  });

  const analytics = await dub.analytics.retrieve({
    folderId: "clux0rgak00011...",
  });
  ```

  ```go Go theme={null}
  package main

  import(
    "context"
    dubgo "github.com/dubinc/dub-go"
    "github.com/dubinc/dub-go/models/operations"
    "log"
    "os"
  )

  func main() {
    ctx := context.Background()

    s := dubgo.New(
      dubgo.WithSecurity(os.Getenv("DUB_API_KEY")),
    )

    res, err := s.Analytics.Retrieve(ctx, operations.RetrieveAnalyticsRequest{
      FolderId: dubgo.String("clux0rgak00011..."),
    })
  }
  ```

  ```python Python theme={null}
  import os
  import dub
  from dub.models import operations

  d = dub.Dub(
    token=os.environ['DUB_API_KEY'],
  )

  res = dub.analytics.retrieve(request={
    "folder_id": "clux0rgak00011...",
  })
  ```

  ```ruby Ruby theme={null}
  require 'dub'

  s = ::OpenApiSDK::Dub.new
  s.config_security(
    ::OpenApiSDK::Shared::Security.new(
      token: "DUB_API_KEY",
    )
  )

  req = ::OpenApiSDK::Operations::RetrieveAnalyticsRequest.new(
    folder_id: "clux0rgak00011...",
  )

  res = s.analytics.retrieve(req)
  ```

  ```php PHP theme={null}
  declare(strict_types=1);

  require 'vendor/autoload.php';

  use Dub;
  use Dub\Models\Operations;

  $sdk = Dub\Dub::builder()->setSecurity('DUB_API_KEY')->build();

  $request = new Operations\RetrieveAnalyticsRequest(
    folderId: "clux0rgak00011...",
  );

  $response = $sdk->analytics->retrieve(
    request: $request
  );
  ```

  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.dub.co/analytics?folderId=clux0rgak00011... \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json'
  ```
</CodeGroup>